History: CSS Variables in Tiki
Source of version: 13 (current)
Copy to clipboard
{syntax type="markdown" editor="wysiwyg"} {HTML()}<style>.tab-pane { padding: 0.5rem; } .wikitable tr .wikicell:first-child { min-width: 33%; }</style>{HTML}
## Background info on CSS variables
{QUOTE()}
Custom properties (sometimes referred to as CSS variables or cascading variables) are entities defined by CSS authors that contain specific values to be reused throughout a document. They are set using custom property notation (e.g., ` ~np~<strike>~/np~main-color: black;)` and are accessed using the `var()` function (e.g., `color: var(~np~</strike>~/np~main-color);` ).
\-- [https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties]
{QUOTE}
See also: [https://css-tricks.com/a-complete-guide-to-custom-properties/]
## CSS variables in Bootstrap
There were just 28 CSS variables in Bootstrap 4 ([https://getbootstrap.com/docs/4.0/getting-started/theming/#css-variables]). As of Bootstrap 5.2, this number, for root CSS variables, is up to approximately 70 ([https://getbootstrap.com/docs/5.2/customize/css-variables/#root-variables]). Root CSS variables have global scope. There are also component variables, with narrow scope, such as those used for [https://getbootstrap.com/docs/5.2/content/tables/#how-do-the-variants-and-accented-tables-work|tables] and [https://getbootstrap.com/docs/5.2/components/navbar/#css|navbars], and as shown below in the examples of the top and topbar zone CSS variables.
## The Tiki CSS variable syntax
To distinguish SCSS variables created specifically for Tiki from Bootstrap or other SCSS variables, they have a `$tiki-` prefix (implementation of this is a work in progress). The same pattern is used for Tiki's CSS variables, with ` --tiki- `. (The prepended two hyphens are the standard notation for CSS variables.)
## CSS variables currently used by Tiki
{TABS(name="user_tabset_01" tabs="Tiki 26|Tiki 25" toggle="y" panelbgcolor="var(--bs-secondary-bg)")}
### Top and topbar module zones (navbars)
For Tiki 26, the CSS variables used for the top and topbar module zones (navbars) have been reorganized. Instead of CSS variables with specific color ("light" or "dark") names, in Tiki 26 the variable names don't mention color themselves. Instead, neutral-color names are used in each combination of color and location — 1) *light / top*, 2) *light / topbar*, 3) *dark / top*, and 4) *dark / topbar*. This will facilitate using them with whole-website color mode switching in Tiki 26, which uses Bootstrap 5.3.
| **Selector (Bold) and Variable Name** | **Description** |
|---|---|
| **.tiki-top-nav-light {** | Top module zone, light option (set in Look and Feel admin) |
| **.tiki-top-nav-dark {** | Top module zone, dark option (set in Look and Feel admin) |
| --tiki-top-bg | Top module zone background color (CSS color, gradient, image, etc.) |
| --tiki-top-color | Links in top module zone |
| --tiki-top-hover-color | Hover color for " |
| --tiki-top-hover-bg | Color of link background during pointer hover |
| *Link active color isn't implemented . . .* | *. . . but can be if requested.* |
| *Link active background isn't implemented . . .* | *. . . but can be if requested.* |
| --tiki-top-text-color | Applies to text such as log-in form labels in header mode ([https://gitlab.com/tikiwiki/tiki/-/merge_requests/3611 | added] for Tiki 26.1). |
| --tiki-top-border | [https://developer.mozilla.org/en-US/docs/Web/CSS/border-style | Style] and color of border on the top zone, such as ` solid black ` |
| --tiki-top-border-width | Width of border on the top zone, such as ` 2px ` |
| --tiki-top-box-shadow | Box shadow on the top zone, such as ` 0px 2px 5px grey ` . Note that "0" requires a unit (px, etc.) in a CSS variable. Also, normally there is no space around the top navbar so a shadow is not likely to be visible unless spacing is configured for it. |
| **}** | |
| | |
| **.tiki-topbar-nav-light {** | Topbar module zone, light option (set in Look and Feel admin) |
| **.tiki-topbar-nav-dark {** | Topbar module zone, light option (set in Look and Feel admin) |
| --tiki-topbar-bg | Topbar background color (CSS color, gradient, image, etc.) |
| --tiki-topbar-color | Color of text, etc. other than links. This is available but not currently used. Covers only immediate child elements. |
| --tiki-topbar-hover-color | Hover color for " |
| *Link active color isn't implemented . . .* | *. . . but can be if requested.* |
| --tiki-topbar-hover-bg | Color of link background during pointer hover |
| *Link active background color isn't implemented . . .* | *. . . but can be if requested.* |
| --tiki-topbar-text-color | Applies to text such as log-in form labels in header mode ([https://gitlab.com/tikiwiki/tiki/-/merge_requests/3611 | added] for Tiki 26.1). |
| --tiki-topbar-border | [https://developer.mozilla.org/en-US/docs/Web/CSS/border-style | Style] and color of border on the topbar zone, such as ` solid black ` |
| --tiki-topbar-border-width | Width of border on the top zone, such as ` 2px ` |
| --tiki-topbar-box-shadow | Box shadow on the top zone, such as ` 0px 2px 5px grey` . Note that "0" requires a unit (px, etc.) in a CSS variable. Also, a shadow may not be visible unless spacing is configured for it. |
| **}** | |
| |
#### Site Title and Subtitle (Logo module)
| **Selector (Bold) and Variable Name** | **Description** |
|---|---|
| **:root {** | Use ":root" for global application (all layouts and pages, etc.) |
| --tiki-site-title-font-size | Font size and weight (this row and below) for the logo module in the Classic Tiki and Single Container layouts. (These variables are used in themes/base_files/scss/_tiki-modules.scss.) |
| --tiki-site-title-font-weight | |
| --tiki-site-subtitle-font-size | |
| --tiki-site-subtitle-font-weight | |
| --tiki-fixed-top-site-title-font-size | Font size and weight (this row and below) for the logo module in the Classic Bootstrap (layout_social, fixed-top) layout (likely smaller than for the static position). |
| --tiki-fixed-top-site-title-font-weight | |
| --tiki-fixed-top-site-subtitle-font-size | |
| --tiki-fixed-top-site-subtitle-font-weight | |
| --tiki-site-title-color | (These variables are used in an inline style in templates/modules/mod-logo.tpl.) |
| --tiki-site-subtitle-color | |
| **}** | |
| |
### Unified Admin Backend
The variables below are used on the new (Unified Admin Backend) admin pages for the top and side navbars and menus. (The top navbar's background is specified separately with a different selector, below.\*)
| **Selector (Bold) and Variable Name** | **Description** |
|---|---|
| **.tiki .tiki-admin-top-nav-light, <br /> .tiki .tiki-admin-aside-nav-light {** | Selectors used by "Admin navbar background color" ***Light*** option |
| **.tiki .tiki-admin-top-nav-dark, <br /> .tiki .tiki-admin-aside-nav-dark {** | Selectors used by "Admin navbar background color" ***Dark*** option |
| --tiki-admin-top-nav-color | Link color (link labels and icons) in the top navbar |
| --tiki-admin-top-nav-hover-color | Link color when pointer hovers, in the top navbar |
| --tiki-admin-top-nav-hover-bg | Color of link background when pointer hovers |
| --tiki-admin-aside-nav-bg | Background color of side-column menu. Normally specified by the theme to be the same as top navbar background color but, like all of these selectors, it can be overridden. |
| --tiki-admin-aside-nav-color | Link color (text and icons) in the side menu |
| --tiki-admin-aside-nav-hover-color | Link color when pointer hovers, in the side menu |
| --tiki-admin-dropdown-bg | Background color of top navbar menu dropdowns, including the login module, etc., and of the side menu dropdown sections. |
| --tiki-admin-dropdown-link-color | Link color (link labels and icons) in the menu dropdowns |
| --tiki-admin-dropdown-link-hover-color | Link label and icon color when pointer hovers, in the menu dropdowns |
| --tiki-admin-dropdown-link-hover-bg | Link background color when pointer hovers, in the menu dropdowns |
| **}** | |
| | |
| **.tiki.tiki-admin .top_modules.navbar-light-parent {** | Selector used by "Admin navbar background color" ***Light*** option |
| **.tiki.tiki-admin .top_modules.navbar-dark-parent {** | Selectos used by "Admin navbar background color" ***Dark*** option |
| --tiki-admin-top-nav-bg | Background color of the top navbar |
| **}** | |
| |
### Miscellaneous
| **Selector (Bold) and Variable Name** | **Description** |
|---|---|
| **:root {** | Applies globally. |
| ~np~<strike>tiki-page-content-top-margin~/np~ | To create white space at the top of the content area, below the site header, input code just like this in the Look & Feel admin CSS Customization form, with a pixel, em, or rem size. Example: *:root { tiki-page-content-top-margin: 15px; }*. Other global CSS variables can also be placed in this array (between the curly braces). |
| **}** | |
/////
| **Selector and Variable Name** | **Notes** |
|---|---|
| **:root {** | |
| --tiki-top-bg-light | |
| --tiki-top-light-color | |
| --tiki-top-light-link-color | |
| --tiki-top-light-link-hover-color | |
| --tiki-top-light-link-hover-bg | |
| --tiki-top-light-box-shadow | |
| | |
| --tiki-topbar-bg-light | |
| --tiki-topbar-light-color | |
| --tiki-topbar-light-link-color | |
| --tiki-topbar-light-link-hover-color | |
| --tiki-topbar-light-link-hover-bg | |
| --tiki-topbar-light-box-shadow | |
| | |
| --tiki-topbar-light-border | |
| --tiki-topbar-border-width | for light and dark topbars |
| | |
| --tiki-top-bg-dark | |
| --tiki-top-dark-color | |
| --tiki-top-dark-link-color | |
| --tiki-top-dark-link-hover-color | |
| --tiki-top-dark-link-hover-bg | |
| --tiki-top-dark-box-shadow | |
| | |
| --tiki-top-dark-border | |
| --tiki-top-border-width | |
| | |
| --tiki-topbar-bg-dark | |
| --tiki-topbar-dark-color | |
| --tiki-topbar-dark-link-color | |
| --tiki-topbar-dark-link-hover-color | |
| --tiki-topbar-dark-link-hover-bg | |
| --tiki-topbar-dark-box-shadow | |
| | |
| --tiki-topbar-dark-border | |
| | |
| --tiki-static-top-light-border | this and the following, for Classic Tiki and Single Container layouts |
| --tiki-static-top-dark-border | |
| **}** | |
| | |
| **header.navbar.fixed-top {** | These are very explicit because they are used in the calculation of the site logo image; their scope is limited to header.fixed-top. |
| --tiki-fixed-top-border-top-width | |
| --tiki-fixed-top-border-right-width | |
| --tiki-fixed-top-border-bottom-width | |
| --tiki-fixed-top-border-left-width | |
| --tiki-top-light-border-color | |
| --tiki-top-dark-border-color | |
| **}** | |
Related, there are also these CSS variables for the site title and subtitle, in fixed-top position (Basic Bootstrap layout) and static position (Classic Tiki and Single Container layouts) and their default values:
~pp~
--tiki-fixed-top-site-title-font-size: 1.8rem; // Fixed-top position (Basic Bootstrap layout)
--tiki-fixed-top-site-title-font-weight: 700;
--tiki-fixed-top-site-subtitle-font-size: 1.4rem;
--tiki-fixed-top-site-subtitle-font-weight: 400;
--tiki-site-title-font-size: 2rem; // Static position (Classic Tiki and Single Container layouts)
--tiki-site-title-font-weight: 700;
--tiki-site-subtitle-font-size: 1.5rem;
--tiki-site-subtitle-font-weight: 400;
~/pp~
{TABS}
---
- ## Theme-specific CSS variables
CSS variables are used by some Tiki themes already for color mode compliance or for situations where site admins might want to configure the theme's appearance or behavior in a particular way.
### Background image path
A CSS variable can represent the path to an image file used for the background of some page element, like this:
{CODE(caption="From the Feb12 theme's _tiki-selectors.scss file")}
.middle {
background: var(--tiki-feb12-middle-bg);
padding-bottom: 20px;
}
{CODE}
Then ` --tiki-feb12-middle-bg ` is specified differently, to fetch different files, or one file or no file, depending on whether light or dark color mode is being used:
{CODE(caption="From the Feb12 theme's _css-variables.scss file")}
:root {
--tiki-feb12-middle-bg: #ffffff url(../images/page.jpg) repeat-x;
}
[data-bs-theme="dark"] {
--tiki-feb12-middle-bg: transparent;
{CODE}
## Defining CSS variables
As the docs on CSS variables show, they are placed in one or more arrays, each headed by a selector. These arrays, for a theme, are usually in the theme's `_css-variables.scss` file, or they can be placed at the end of the theme's `_variables.scss` file. This positions the arrays after the SCSS variables are defined, which CSS variables may require.
## Using Look & Feel CSS Customization
To redefine one or more of the CSS variables, the variable name and the new value for it can be input in the Look & Feel admin customization text area, inside the `:root ` array or under another appropriate selector, as indicated in the tables above. This could also be in a custom.css file.
## Future possibilities
- A dedicated Look & Feel "CSS Variables" text area provided so that just the variables could be entered and the root array syntax would be added on the backend.
- New Tiki CSS variables in addition to those listed above — what other Tiki page elements should easy customization be enabled for?
- Site color controls (or other controls) available to site users on the public side, such as for dark mode, like switching themes but not needed a page refresh. — This is implemented in Bootstrap 5.3 and will be in the upcoming Tiki 26 release.
## References:
- https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
- https://css-tricks.com/a-complete-guide-to-custom-properties/
- https://blog.getbootstrap.com/2022/05/16/using-bootstrap-css-vars/
- https://getbootstrap.com/docs/5.3/customize/color-modes/ (This is already in development for Tiki.)
- https://getbootstrap.com/docs/5.2/customize/css-variables/
- https://getbootstrap.com/docs/4.0/getting-started/theming/#css-variables
- https://pedromarquez.dev/blog/2022/7/dark-mode-css