14 Use CSS and Themes in Oracle JET Apps
Note:
Starting in Oracle JET release 9.0.0, the Redwood theme is the default theme for all new JET web apps.About the Redwood Theme Included with Oracle JET
Oracle Redwood Design System is the Oracle standard for app look and feel. It is being implemented company-wide to unify the user interface of all Oracle product offerings and is implemented in Oracle JET as the Redwood theme.
Oracle JET takes this opportunity to refresh the toolkit look and feel with this dynamic, forward thinking design system and also to introduce all new components that rely on the user experience of Oracle Redwood Design System, such as JET waterfall layout and JET stream list component.
All starter templates use the Redwood theme. Because all apps will be created with
the Redwood theme by default, you no longer need to specify the
theme type when using the JET Tooling create
and serve commands. There are no theme
variations specific to the mobile platforms. For details, see
Create an App with the Redwood Theme.
If you have an existing app that you want to migrate from the Alta theme, you can migrate to the current JET release and configure the app to run with the out-of-the-box CSS for the Redwood theme. For details, see Migrate to the Redwood Theme CSS.
Customizing Redwood theme is supported by working with CSS variables. For details, see About CSS Variables and Custom Themes in Oracle JET.
CSS Files Included with the Redwood Theme
Oracle JET includes CSS files designed for display on web browsers that implement Oracle Redwood Design System. In JET, the Redwood theme includes minified and readable versions of the CSS.
Starting in Oracle JET release 9.0.0, app themes are based on Redwood theme, a theme for both mobile and browser apps that replaces the multiple themes needed in prior releases.
The Redwood CSS is included with the Oracle JET distribution and is located in the /<app_root>/node_modules/@oracle/oraclejet/dist/css/redwood folder. The Redwood CSS distribution contains the following files:
-
oj-redwood.css: Readable version of the CSS for the out-of-the-box Redwood theme -
oj-redwood-min.css: Minified version of the CSS for the out-of-the-box Redwood theme
In addition, the Redwood theme includes the following CSS:
-
oj-redwood-notag.css: Readable version of the CSS without tag selectors -
oj-redwood-notag-min.css: Minified version of the CSS without tag selectors.
For additional details about Oracle JET theming and tag selectors, see Disable JET Styling of Base HTML Tags.
Always use the recommended standards to work with your CSS and themes. For more information, see Best Practices for Using CSS and Themes.
Important:
Do not override the style classes in the Oracle JET CSS distribution. The CSS files shipped with Oracle JET are considered private and must not be modified. Such modifications may prevent you from migrating your theme to a future release.Create an App with the Redwood Theme
The Redwood theme is the Oracle JET implementation of Oracle Redwood Design System and is the default theme for apps that you create in JET release 9.0.0 and later.
Oracle Redwood Design System is the new Oracle user experience design language, and Redwood theme is the recommended theme if you are creating a new JET web app.
You use the ojet create command to scaffold an app that by default
uses the Redwood CSS files provided with the Redwood theme distribution. When you
build the app, the JET Tooling loads redwood.css.
When you create your app, JET Tooling will use the out-of-the-box Redwood theme file
as configured by the property defaultTheme=redwood in the
oraclejetconfig.json file. There are no other configuration
settings needed for the tooling to use the redwood.css when you
build and run the app.
{
"paths": {
...
},
"defaultBrowser": "chrome",
"sassVer": "8.0.0",
"defaultTheme": "redwood",
"architecture": "mvvm",
"generatorVersion": "16.0.0"
}Customization of the theme and styling of individual JET components is supported by overriding JET CSS variables. For details about overriding CSS variables, see Work with Custom Themes and Component Styles.
To create an app with the Redwood theme:
Adjust the Scale of the Redwood Theme
Apps and their users have different scale needs and requirements. The Redwood theme supports three different scale sizes.
The Redwood theme by default uses a large scale size. The large scale is recommended for lower-density pages and is optimized for readability and human scale.
The medium scale is more compact than Redwood's default scale and is designed to increase efficiency by allowing more data to be shown above the page's fold.
The small scale has highly compact proportions and is designed for canvas-style tools with a high level of information and UI density. This scale is not touch-friendly and should therefore only be used on desktop apps.
To change the Redwood theme to use a small or medium scale, use the Oracle JET scale classes oj-scale-sm or oj-scale-md, respectively. Add these classes to the html element in your app's index.html file.
<html class="oj-scale-md">
<!-- content -->
</html>The entire page must be one of these scales—specifying different scales on a single page is not supported.
Best Practices for Using CSS and Themes
Use the recommended styling standards for creating CSS and themes in your web app. These practices apply to all themes in Oracle JET.
| Standard | Details | Example |
|---|---|---|
|
Never override Oracle JET classes |
While there are ways to override Oracle JET CSS style classes containing the
|
|
|
Use mobile-first design |
Apps should be mobile first, meaning that they should work on a phone and tablet. This means they must be touch friendly, including sizing tap targets appropriately. There is no hover in mobile, so the design should not rely on the use of hover. |
|
|
Follow naming conventions |
Use the For example, if you are writing a branding bar that contains a header element for your company acme, then choose Including a namespace is important in order to minimize the chances of your base CSS
(for example, one provided by a client) on the page affecting your app's CSS and
vice-versa. For example, if your CSS and the client-provided CSS both have a class
named Client CSS: Using |
|
|
Use only Oracle JET public classes |
Use only the public classes documented in the Oracle® JavaScript Extension Toolkit (JET) Styling Reference. All other Oracle JET classes are considered private and subject to change without notice. |
|
|
Minimize custom CSS |
Oracle JET has CSS Utility classes that help you minimize custom CSS. The following list identifies the JET’s CSS Utility classes that can assist you:
When you use Oracle JET CSS utility classes in your app, you also ensure compatibility with the Oracle JET-provided theme. For more details see the CSS Utility classes demos in the Oracle JET Cookbook and the API Reference for Oracle® JavaScript Extension Toolkit (Oracle JET) . |
|
|
Don’t set the font family in the CSS |
The app should set the font family for text once on the root of the page which allows the app to change the font family as needed. In order to blend in with the font family chosen by the app, do not set the font family in the CSS. |
|
|
Use REM for font sizes and CSS styles |
Consider using REM (root em) for font sizes and other CSS style properties where
relative sizing allows your app to scale based on the root |
|
|
Add bi-directional (BIDI) styling support |
Oracle JET apps are expected to set |
|
|
Use |
When Oracle JET detects high contrast mode, it places the |
|
|
Avoid |
Avoid the use of |
|
|
Optimize image use |
All image systems have advantages and disadvantages. See Work with Images to decide if icon fonts are right for you. Always consider performance when using images. For tips, see Add Performance Optimization to an Oracle JET App |
Here is one example of an overridden Oracle JET class that is not allowed:
Avoid using DOCTYPE Requirement
In order for Oracle JET's theming to work properly, you must include the following line at the top of all HTML5 pages:
<!DOCTYPE html>
If you don't include this line, the CSS in your app may not function as expected. For example, you may notice that some elements aren't properly aligned.
Tip:
If you create an Oracle JET app using the tooling or one of the sample apps, this line is already added for you, and you do not need to add it yourself.Set the Text Direction
If the language you specify uses a right-to-left (RTL) direction instead of the default left-to-right (LTR) direction, such as Arabic and Hebrew, you must specify the dir attribute on the html tag: <html lang=name dir="rtl">.
For example, the following code specifies the Hebrew Israel (he-IL) locale with right-to-left direction enabled:
<html lang="he-IL" dir="rtl">Oracle JET does not support multiple directions on a page. The reason this is not supported is that the proximity of elements in the document tree has no effect on the CSS specificity, so switching directions multiple times in the page may not work the way you might expect. The code sample below shows an example.
<style>
[dir=ltr] .foo {color: blue}
[dir=rtl] .foo {color: red}
</style>
<span dir="rtl">
<span dir="ltr">
<span class="foo">You might think I will be blue because dir=ltr is on,
a closer ancestor than dir=rtl. But css doesn't care
about proximity, so instead I am red
(because [dir=rtl] .foo {color: red} was defined last).
Isn't that surprising?
</span>
</span>
</span>For more information about localizing your app and adding bidirectional support, see Enable Bidirectional (BiDi) Support in Oracle JET. For more information about CSS specificity, see https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity.
Work with Images
Oracle JET uses icon fonts whenever possible to render images provided by the Redwood theme. When icon fonts are not possible, Oracle JET uses SVG images.
You may also find the following topics helpful when working with images.
Image Considerations
There are a variety of ways to load icons, such as sprites, data URIs, icon fonts, and so on. Factors to consider when choosing an image strategy include:
-
Themable: Can you use CSS to change the image? Can you replace a single image easily?
-
High contrast mode: Does the image render properly in high contrast mode for accessibility?
-
High resolution support: Does the image look acceptable on high resolution (retina) displays?
-
Image limitations: Are there limitations that impact your use case? For example, icon fonts are a single color, and small SVG images often do not render well.
-
Performance: Is image size a factor? Do you need alternate versions of an image for different resolutions or states such as disabled, enabled, hover, and active?
Icon Font Considerations
Oracle JET uses icon fonts whenever possible because icon fonts have certain advantages over other formats.
-
Themable: You can use style classes to change their color instead of having to replace the image, making them very easy to theme.
-
High contrast mode: Icon fonts are optimal for high contrast mode as they are considered text. However, keep in mind that you can't rely on color in high contrast mode, and you may need to indicate state (active, hover, and so on) using another visual indicator. For example, you can add a border or change the icon font's size. For additional information about Oracle JET and high contrast mode, see Configure High Contrast Mode.
-
High resolution: Icon fonts look good on a high resolution (retina) display without providing alternate icons.
-
Performance: You can change icon font colors using CSS so alternate icons are not required to indicate state changes. Alternate images are also not required for high resolution displays.
Icon fonts also have disadvantages. It can be difficult to replace a single image, and they only show one color. You can use text shadows to provide some depth to the icon font.
Work with Custom Themes and Component Styles
When you add a custom theme to your scaffolded app, Oracle JET adds CSS variable definition files that you can modify to customize your app’s look and feel.
About CSS Variables and Custom Themes in Oracle JET
JET introduced the Redwood theme in release 9.0.0. In release 10.0.0, support for theming based on the out-of-the-box Redwood theme with CSS variables instead of Sass variables was introduced. Starting with JET release 11.0.0, you can also create a custom theme based on another out-of-the-box theme, Stable, that JET provides. We refer to these two themes (Redwood and Stable) as base themes.
Choose the Stable theme as the base theme for your custom theme if you want to reduce the likelihood that future updates to the Redwood theme affect the custom theme that you develop. Use Redwood as the base theme for your custom theme if you want to inherit future updates to the Redwood theme. Redwood theme implements the look and feel for Oracle apps, and future changes will be made to address Oracle’s requirements. The Stable theme, as the name suggests, intends to be stable and unlikely to change frequently. That said, Oracle cannot guarantee that the Stable theme will remain unchanged. We may, for example, need to change the Stable theme to incorporate component enhancements. As of its initial release (JET release 11.0.0), Stable theme implements the same component behavior as the Redwood theme.
Options to theme your app using CSS variables include:
- Add variable overrides in your app's
/appRootDir/src/css/app.cssfile while your app continues to use the Redwood or Stable CSS file. Choose this option if you want to add a limited number of app-specific overrides to the base theme. - Use the JET CLI to create a new custom theme that your app will use. Choose this option if you want to make extensive changes, or you want to make changes that will be reused by a variety of apps.
Use the Theme Builder app (links below) to assist you with these tasks as it contains a variety of JET components that allow you to preview the affect of changes to CSS variables.
Note that Sass is not completely eliminated in JET; JET continues to use Sass when
you work with the Redwood theme for bundling and there are a few cases, for
example in media queries, where CSS variables aren't supported. For the few
exceptions, Sass variables are needed (such as
$screenSmallMinWidth and
$screenSmallMaxWidth). Therefore Sass is still part
of the theming toolchain when you use ojet add theming in
the JET CLI. If you use Sass to generate your own styles and don't rely on
any JET Sass variables, then you can continue to use Sass as before.
However, if you do rely on JET Sass variables, then most of those Sass
variables will no longer be available, see the Sass-based Theme Builder -
Migration tab for information about how to migrate JET Sass variables to CSS
variables.
Use these links to view Theme Builder pages:
- CSS Variable Theme Builder
- CSS Variable Theme Builder - Instruction Tab
- Sass-based Theme Builder - Migration Tab
Here are some recent significant updates in JET's support of theming.
| Release | Event |
|---|---|
| JET 9.0.0 | You can use the Redwood CSS out of the box, without any changes. |
| JET 10.0.0 |
|
| JET 11.0.0 | You can choose between adding a custom theme to your JET app based on the Stable theme or the Redwood theme. Choose the Stable theme as the base theme for your custom theme if you want to reduce the likelihood that future updates to the Redwood theme affect the custom theme that you develop. Use Redwood as the base theme for your custom theme if you want your custom theme to inherit future updates to the Redwood theme. |
Add Custom Theme Support with the JET CLI
You can use Oracle JET Tooling to add a custom theme to your app.
/src/themes folder.
To add theming support:
Modify the Custom Theme with the JET CLI
You can override CSS variables defined by the base theme in the custom theme that you add to your JET app.
You modify the generated file
_<themeName>.cssvars.settings.scss located in the
/src/themes/<themeName>/web folder. This file
contains the list of available JET CSS variables in :root where you
set values for the variables to apply application-wide to the JET components.
Before you begin:
- Install the theming toolchain and configure a custom theme, as described in Add Custom Theme Support with the JET CLI. The
themesfolder with custom theme settings files are added to your application source. - Examine the App Wide Theming section in the Oracle JET Cookbook for examples.
- Refer to the JET CSS Variables section of the JET API reference doc for an overview of the CSS variables and their values.
- Optionally, download and install the Theme Builder app. The Theme Builder app uses the CLI and shows various JET components to easily see the effect of a creating a theme. See CSS Variable Theme Builder - Instruction Tab.
To override base theme CSS variables in your application CSS:
Modify the Custom Theme with Theme Builder
You can use the JET Theme Builder application to override CSS variables defined by the Redwood or Stable theme and reuse the generated theme definition files to theme your own application.
Theme Builder is a JET application that contains a variety of JET components that allow you to visualize look and feel changes that you make by overriding CSS variable values. Because Theme Builder is a JET application, the process of theming uses the same theme definition files that your application relies on when you create a custom theme. This allows you to use the Theme Builder application to create a custom theme and then reuse those generated theme definition files in your own application. Alternatively, you can use Theme Builder strictly as a tool to learn the names of the CSS variables, and then work with JET Tooling to create a custom theme in your own application, as described in Modify the Custom Theme with the JET CLI.
To work with Theme Builder, you download the application as described in the Theme
Builder - Instruction tab. You then use the ojet add theming and
ojet create theme commands in the JET CLI to generate the needed theme
definition files that allow you to override CSS variables and create a custom theme CSS.
When you are satisfied with the custom CSS in Theme Builder, you will then prepare your own
application to generate CSS from theme definition files before copying over the theme
definition files you modified in Theme Builder.
Before you begin:
- Download and install the CSS Variable Theme Builder - Instruction Tab application. You will modify the generated theme definition files to override Redwood CSS variables and reuse the modified files in your application.
- In the application that you want to reuse the Theme Builder generated CSS, install
the theming toolchain and configure a custom
theme, as described in Add Custom Theme Support with the JET CLI. The
themesfolder with custom theme definition files is added to your application source. This is the folder that you will copy Theme Builder theme definition files into.
To reuse a Theme Builder generated CSS in your application:
Optimize the CSS in a Custom Theme
By default when you build the application, JET Tooling loads CSS with all Redwood style classes enabled. You can configure the CSS to use just the styles required by the components of your application.
With the custom theme settings files added to the /src/themes folder of your project by the JET Tooling, you can reduce the size of the Redwood CSS by commenting and uncommenting import statements in the settings files for specific JET component style classes. With the appropriate import settings completed, JET Tooling will process the CSS settings files and load CSS for only the JET components you specified.
Before you begin:
- Install the theming toolchain and configure a custom theme, as described in Add Custom Theme Support with the JET CLI. The
themesfolder with custom theme settings files are added to your application source.
To reduce CSS by limiting component CSS:
Style Component Instances with CSS Variables
When you want to customize the appearance of a component instance, you create style classes that override the CSS variables at the selector level and then apply the style classes to the component instance in your app’s HTML.
You can define style classes in your app.css file in the
/src/css folder or, when you theme your application, in the generated
_<themeName>.cssvars.settings.scss theme file located in the
/src/themes/<themeName>/web folder. The
_<themeName>.cssvars.settings.scss file contains the list of available
CSS variables in :root, where you can set values for the variables to apply
application-wide to the JET components. When you want to define a style class to customize
individual component instances, you must add your style class definitions with CSS overrides
so they appear at the end of the file, after all CSS variables and they must not be
contained within :root.
Note that while most customization is done with CSS variables, but in a few cases, such as for media queries, Sass variables are needed.
Before you begin:
- Examine the Component Styling section in the Oracle JET Cookbook for examples.
- Refer to the JET CSS Variables section of the JET API reference doc for an overview of the CSS variables and their values.
- Optionally, download and install the CSS Variable Theme Builder - Instruction Tab application when you want to learn about the available CSS variables in this interactive demo application. Follow the instructions online to modify the theme definition files to learn how CSS variable overrides change the demo tool UI.
To override JET CSS variables to style component instances:
Disable JET Styling of Base HTML Tags
By default, Oracle JET applies styles to HTML tag elements such as
a, h1,
h2, and so on. This feature makes
it easier to code a page since you do not have to apply
selectors to each occurrence of the element.
If you do not want to apply styles to all base HTML tags by default in your custom theme, you can specify that Oracle JET generate style classes that can be placed on tags. The base theme CSS styles loaded at build time are controlled by import statements in custom theme settings files that you can optionally add to your project. To work with the CSS settings files in your project, you need to add theming support to the app and then create a custom theme.
With the custom theme settings files added to the /src/themes folder
of your project, you can comment out an import statement
that by default enables importing all JET component styles
and add in its place the no-tag version of the import
statement. With the appropriate import setting completed,
when you build your app, JET Tooling will process the CSS
settings files and load CSS for all JET components, but
without the JET style classes for HTML base tags. To apply
JET style to the HTML tags with the no-tag import enabled,
you must explicitly set the JET style class on the desired
HTML tag. For example, you can apply the JET style for links
on the HTML anchor tag, like this <a
class=oj-link>.
The following table lists the HTML tags with default Oracle JET tag styles and the corresponding Oracle JET style class that you can optionally apply when you enable the no-tag import statement.
| HTML Tag | Oracle JET Style Class |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Before you begin:
- Install the theming toolchain and configure a custom theme, as described in Add Custom Theme Support with the JET CLI. The
themesfolder with custom theme settings files are added to your app source.
To disable JET styling of base HTML tag: