Introduction to CSS Variables in Oracle APEX

Wednesday, October 9, 2024

TL;DR: CSS variables store reusable values for stylesheets. Oracle APEX extensively uses CSS variables in its Universal Theme. This is useful for APEX developers as they can easily and safely modify default styles and reuse them in their own templates.

Understanding CSS Variables

CSS variables (also known as "CSS custom properties") allow you to store values that can be reused throughout your stylesheets. They are defined using the double-dash (`--`) prefix followed by a variable name and a value. Here's an example:

body {
  --my-font: "Times New Roman";
}

In this case, we've created a variable named `--my-font` and assigned it the value "Times New Roman". It is currently only defined and has no effect on the page.

To use this variable, we can style header elements by referencing variables using the `var()` function:

h2 {
  font-family: var(--my-font);
}

Now, the `<h2>` element will use the font defined in the `--my-font` variable.

CSS Variable Cascading and Overriding

CSS variables follow the cascading nature of CSS. If you define a variable at a higher level, like the `<body>` element, it can be overridden by a more specific selector. Let’s take our example and add another `<h2>` with the class `special-h2`. We can create a rule for this specific element and overwrite the value of our variable:

body {
  --my-font: "Times New Roman";
}


h2 {
  font-family: var(--my-font);
}


h2.special-h2 {
  --my-font: "Arial";
}

We now have two values for our variable, but as the new rule has a more specific selector matching exactly the new `<h2>` element, Arial overwrites Times New Roman for it.

We can also debug what is going on in our browser developer tools on our new special `<h2>` element showing the Times New Roman rule struck through as it is being overwritten:

CSS Variables in Oracle APEX

Oracle APEX extensively utilizes CSS variables in its Universal Theme. Let’s look at what is going on behind the scenes of buttons.

Inspecting APEX Buttons

By inspecting the buttons using browser developer tools, we can observe that APE uses CSS variables for various properties such as background color, text color, and more.

APEX follows the "Don't Repeat Yourself" (DRY) principle by defining colors once and referencing them using variables. For example, the `--a-button-focus-background-color` does not redefine the same color again; instead, it references the `--a-button-hover-background-color` variable.

In another rule, a property has multiple calls to a variable. What is going on here? The var function allows you to pass a second value as a fallback when the variable is not defined. E.g. `font: var(--my-font, “Arial”);`. A call to another `var()` function is also possible.

This is useful in two cases:

By default, only the fallback is used. Users can define the first variable themselves if they want to easily overwrite the default styles without having to touch or interfere with existing rules.
Some variables are only defined under specific conditions. In this example, `a-button-state-background-color` is being set on hover or focus and thus automatically gets applied.

Customizing APEX Variables

Keep in mind that APEX still has the Theme Roller. This post focuses on CSS variables, but you can and should still use the Theme Roller for its supported scope. However, CSS variables can go much further.

As APEX doesn’t plan for Case 1, we have to overwrite the values of the variables to customize the look. But this is not an issue and is still a much better approach than one where no variables are available.

Since we have already looked at the variables that power the button styles, we can now easily overwrite their values:

.my-region .t-Button--hot {
  --a-button-background-color: pink;
  --a-button-text-color: black;
}

By changing the values of the CSS variables, you can alter the look and feel of the buttons without directly modifying the APEX stylesheets. The APEX development team recommends this approach, as it is unlikely to break the UI in future releases. At worst, the variable isn’t applied anymore.

APEX Universal Theme CSS Variables Reference

APEX provides a handy reference for CSS variables in the Universal Theme App. These variables cover various aspects of the theme, including color palettes, component backgrounds, borders, shadows, text colors, and more. You can leverage these variables to create a consistent and cohesive design throughout your APEX application without reinventing the wheel.

Theming and Portability

If you use multiple theme styles for your apps, you definitely want to use the APEX CSS variables. In the Vita dark theme, backgrounds are dark, and text is bright. You don't want to break this behavior, so instead use `--ut-component-background-color` and `--ut-component-text-default-color` instead of hard-coded values.

For our button example, we can also use the theme color palette instead of defining our own colors. Color 25 also looks pinky, so let's use this instead:

.my-region .t-Button--hot {
  --a-button-background-color: var(--u-color-25);
  --a-button-text-color: var(--u-color-25-contrast);
}

Changing from the Vita theme to Redwood Light now makes the button look in a fitting, more desaturated shade of pink.

Customizing a Classic Report

Let's apply what we've learned to customize a classic report in APEX. We'll focus on changing the alternate row highlight and header text colors.

Start by inspecting the applied styles in your browser developer tools. On an odd row, you can quickly find the CSS rule responsible for the alternating background color.

The variable `--ut-report-cell-alt-background-color` seems to be the color definition. We can now easily override the color for the whole classic report by selecting the classic report static ID:

#my-cr {
  --ut-report-cell-alt-background-color: rgba(238, 44, 44, 0.5);
}

For the header text, we can see that there isn't a specific table heading color; instead, it uses the variable for link text color:

To only change it for the headers and not the links in the table body, we have to write a more specific CSS rule:

#my-cr th a {
  --ut-link-text-color: green;
}

Now, we only overwrite the color for the links inside a table heading of our classic report. This is our result:

You can also check out and play with this example in the APEX Template Studio.

Conclusion

CSS variables in Oracle APEX provide a powerful and flexible way to customize and theme your applications. Understanding how APEX utilizes these variables and how to override them effectively allows you to create visually appealing and consistent designs without dangerously modifying the core APEX stylesheets.

Remember to scope your overrides appropriately, leverage the Universal Theme CSS Variables reference, and consider portability when building custom components. With CSS variables, you have the tools to make your APEX applications genuinely unique and tailored to your specific requirements.

Philipp Hartenfeller

Product Lead

Expert in all things APEX. Especially fond of full-stack web dev, databases, and JavaScript!

Comments

No comments yet, be the first one to let us know what you think of this article!