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.

Topics:

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 applications, 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.css file 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:

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
  • You can customize the Redwood theme using CSS variable overrides.

  • Alta themes have been deprecated in JET release 10.0.0. If you have an existing theme that extends Alta and you want to migrate it to extend the Redwood theme (and use CSS variables), it is a manual process. There is information on variable migration on the Theme Builder - Migration tab. More information about migrating your application to a Redwood theme can also be found in Migrate to the Redwood Theme CSS. Note that Alta themes will continue to use Sass, and they will not switch to use CSS variables.

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.

When you use the JET Tooling to add theming support to your app, it adds the theme definition files. Adding theming support is a prerequisite step to performing any modifications to the out-of-the-box Redwood or Stable themes.
Creation of the theme generates these theme definition files in the application /src/themes folder.

To add theming support:

  1. In your application’s top-level directory, enter the following command at a terminal prompt to install the theming toolchain.
    ojet add theming
  2. Create the custom theme. This adds the custom theme settings files to your application in a folder named for your custom theme. You must choose between the stable or the redwood theme as the base theme for your custom theme. Choose stable as the base theme if you want to reduce the likelihood that future updates to the Redwood theme affect the custome theme that you develop. Use redwood if you want your custom theme to inherit future updates to the Redwood theme.
    ojet create theme themeName --basetheme=stable|redwood

    For example, the following command creates a custom theme named myTheme that uses the stable theme as the base theme.

    ojet create theme myTheme --basetheme=stable

    The command creates a folder with the custom theme name in the application /src/themes directory.

    src
    |   index.html
    |   
    +---css
    |       
    +---themes
    |   
    |   \---myTheme
    |       |   theme.json
    |       |   
    |       \---web
    |               myTheme.scss
    |               _myTheme.cssvars.settings.scss
    |               _myTheme.optimize-components.scss
    |               _myTheme.sass.settings.scss

    In the directory listing above, the web folder shows the .scss custom theme settings files that you can modify. You’ll find out how to work with these files at the end of this section.

    • _<themeName>.cssvars.settings.scss is the primary file that you will use to create your custom theme. You edit this file to set CSS variable values that are then used by JET components, application-wide. So, for example, to change the primary text color for JET as a whole, you can edit this file by uncommenting and setting the value for --oj-core-text-color-primary.
    • _<themeName>.optimize-components.sccs allows you to tune the overall CSS size of your theme by specifying styling of specific JET components. You do not need to edit this file if you are styling the entire JET component set.
    • _<themeName>.sass.settings.scss defines other customizable aspects of the theme that are not yet supported by CSS variables. This includes media queries and responsive screen sizes. For most theming needs, you will not need to edit this file.
    • <themeName>.scss is the main aggregating file for the theme and is the one the JET Tooling uses to generate the custom CSS at build time. By default it is configured to apply your CSS overrides to all JET components. You may need to edit this file when you minimize the JET component CSS that you want to load or you can specify not to load the CSS for base HTML tags.

    In the myTheme folder, the theme.json file contains the version number of the theme, starting with 0.0.1.

  3. Optionally, in the application root, edit the oraclejetconfig.json file and set the defaultTheme property to the custom theme name that you specified with the ojet create theme command.
    {
    	"paths": {
             ...
    	},
    	"defaultBrowser": "chrome",
           "sassVer": "5.0.0",
    	"defaultTheme": "myTheme",
           "architecture": "mvvm",
    	"generatorVersion": "11.0.0"
    }

    In this sample, myTheme is the name of the custom theme shown in the previous step. When you edit the oraclejetconfig.json file, each time you build or serve the application, you can omit the --theme=<themeName> build command option, and the tooling loads your custom theme.

    After you add support for custom theming to your application, when you build and run the application, the CSS will load the out-of-the-box Redwood or Stable theme that you specified as the value for the --basetheme argument.

    To work with the settings files to customize the theme, you can perform these additional tasks:

    Additionally, the CSS Variables section in the Oracle JET Cookbook includes examples of the type of look and feel customizations described in the above list of topics.

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 themes folder 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:

  1. In the /src/themes/<themeName>/web folder, edit the generated _<themeName>.cssvars.settings.scss theme file and modify the CSS variables under :root that you want to override.

    For example, to change the height of all JET buttons in your application, you can override the JET CSS variable --oj-button-height, like this:

    :root {
      ...
      --oj-button-height: 4rem;
      ...
      }
  2. In the /src/themes/<themeName> folder, edit the generated theme.json configuration file and set the generatedFileType property to the appropriate value:
    • "generatedFileType": "combined"

      Use when you need to change the value of CSS breakpoints, or you want to optimize performance by only downloading the CSS you need. With this option the JET CSS and the customizations are combined into one custom theme file. This custom theme file needs to be regenerated every time that you upgrade the JET version of your app. The following entry appears in the index.html page when you serve your app with this option:

      <!-- injector:theme -->
      	<link rel="stylesheet" href="css/myStableTheme/0.0.1/web/myStableTheme.css" id="css" />
      <!-- endinjector -->

      If you use combined because you need to change the value of CSS breakpoints, you also need to uncomment the following entry in the aggregating file for the theme (appRootDir/src/themes/<themeName>/web/myStableTheme.scss in our example):

      //@import "_myStableTheme.sass.settings.scss";

      You must then uncomment one of the following files:

      // @import "oj/all-components/themes/stable/_oj-all-components.scss";
      or:
      // @import "_myStableTheme.optimize-components.scss";

      If you use combined to optimize performance by only downloading the CSS you need, you must uncomment the following line in the aggregating file for the theme:

      // @import "_myStableTheme.optimize-components.scss";
    • "generatedFileType": "add-on"

      This is the default value. Leave unchanged if you don't need to change the value of CSS breakpoints or optimize performance by only downloading the CSS you need. With this option the theme file just contains the CSS variable overrides, so it can be loaded separately after the base Stable or Redwood CSS file. You do not need to regenerate this theme file every time that you upgrade to a new JET release. The following entries appear in the index.html page when you serve your app if your app uses a custom theme (myStableTheme) that uses the Stable theme as the base theme.

      <!-- injector:theme -->
       <link rel="stylesheet" href="css/stable/11.0.0/web/stable.css" id="css" />
       <link rel="stylesheet" href="css/myStableTheme/0.0.1/web/myStableTheme.css" id="css" />
      <!-- endinjector -->
  3. Build a development version of your application.
    ojet build --theme=<themeName>

    You can omit the --theme option if you set the defaultTheme property in the oraclejetconfig.json file.

    The tooling outputs the built application source to the web build folder in the application's root and populates the /web/css folder with the CSS from the theme that you specified as the base theme when creating a custom theme (Redwood or Stable) and the CSS with your overrides, such as the generated myTheme.css file. The following directory listing shows the generated entries for a theme, myStableTheme, that uses the Stable theme as its base theme. The directory listing includes stable.css and stable.min.css files because the app uses "generatedFileType": "add-on" in the appRootDir/src/themes/myStableTheme/theme.json file.

    web
    |   
    +---css
    |   +---fonts
    |   +---images
    |   +---myThemeStable
    |   |   \---0.0.1
    |   |       +---common
    |   |       \---web
    |   |               myThemeStable.css
    |   |               
    |   +---redwood
    |   |   \---11.0.0
    |   |       \---web
    |   |           +---fonts
    |   |           |       internal_iconfont.woff2
    |   |           |       
    |   |           \---images
    |   |                   avatar-pattern1.png
    |   |                   ...
    |   |                   spinner_full.gif
    |   |                   
    |   \---stable
    |       \---11.0.0
    |           \---web
    |               |   stable.css
    |               |   stable.min.css
    |               |   
    |               +---fonts
    |               \---images
    |                       
    +---js
    \---themes
        \---myThemeStable
            |   theme.json
            |   
            \---web
                    myThemeStable.scss
                    _myThemeStable.cssvars.settings.scss
                    _myThemeStable.optimize-components.scss
                    _myThemeStable.sass.settings.scss

    Theme files with the oj- prefix and -notag suffix provide alternatives to the out-of-the-box Redwood theme that allow you to work with a reduced CSS, as described in Work with Custom Themes and Component Styles.

    To load minified CSS, build the application in release mode.

    ojet build --release
  4. Run your application.
    ojet serve --theme=<themeName>

    Again, you can omit the --theme option if you set the defaultTheme property in the oraclejetconfig.json file.

  5. Optionally, to refine the theme, modify CSS variables in your application's _<themeName>.cssvars.settings.scss theme file.

    The Oracle JET serve process will immediately reload the running application in the browser where you can observe the effect of any CSS variable overrides.

  6. To exit the application, press Ctrl+C at the terminal prompt.

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 themes folder 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:

  1. After you have downloaded Theme Builder and run the commands to support theming, in Theme Builder edit the generated /src/themes/<themeName>/web/_<themeName>.cssvars.settings.scss theme file and begin modifying the Redwood CSS variables under :root that you want to override.
  2. While the Theme Builder application is running, modify CSS variables and visualize the changes in the running application until you are satisfied with the look and feel that you have created.
  3. When you are satisfied with the look and feel in Theme Builder and have no further customizations, press Ctrl+C at the terminal prompt to exit the application.
  4. In the Theme Builder application copy all theme definition files in the /src/themes/<themeName>/web folder and paste them into the /src/themes/<themeName>/web folder of the target application that you have already prepared to work with theming.
  5. Build a development version of the application where you added the theme definition files.
    ojet build --theme=<themeName>

    You can omit the --theme option if you set the defaultTheme property in the oraclejetconfig.json file.

  6. Run your application.
    ojet serve --theme=<themeName>

    Again, you can omit the --theme option if you set the defaultTheme property in the oraclejetconfig.json file.

  7. Optionally, to refine the theme, modify CSS variables in your target application's _<themeName>.cssvars.settings.scss theme file.

    The Oracle JET serve process will immediately reload the running application in the browser where you can observe the effect of any CSS variable overrides.

  8. To exit the application, press Ctrl+C at the terminal prompt.

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 themes folder with custom theme settings files are added to your application source.

To reduce CSS by limiting component CSS:

  1. In the /src/themes/themeName/web folder of your application, edit the aggregating themeName.scss file, and comment out the import statement that by default imports all JET component styles.
    // The import statement contains redwood or stable, depending on the value that you
    // supplied to the --basetheme argument when you created the custom theme.
    //@import "oj/all-components/themes/redwood/_oj-all-components.scss";
    or:
    //@import "oj/all-components/themes/stable/_oj-all-components.scss";
    

    And, then uncomment the import statement to enable compiling with the file that controls the CSS to include.

    @import "_themeName.optimize-components.scss";
  2. Edit the _themeName.optimize-components.scss file and uncomment the import statements for the JET components in your application. Note that the following example demonstrates a theme that uses redwood as the value for the --basetheme argument.
    ...
    //@import "oj/avatar/themes/redwood/oj-avatar.scss";
    //@import "oj/badge/themes/redwood/oj-badge.scss";
    @import "oj/button/themes/redwood/oj-button.scss";
    @import "oj/buttonset-one/themes/redwood/oj-buttonset-one.scss";
    @import "oj/buttonset-many/themes/redwood/oj-buttonset-many.scss";
    //@import "oj/card/themes/redwood/oj-card.scss";
    //@import "oj/chart/themes/redwood/oj-chart.scss";
    ...

    In this example, only the import statement for buttons and button sets are uncommented to include the CSS for those components. All import statements in the _themeName.omptimize-components.scss file remain commented out, by default.

  3. If your application is already running, you can immediately observe the effect of commenting and uncommenting import statements, after you save the changes in the _themeName.optimize-components.scss file. Otherwise, serve your application to enable live reload.
    ojet serve
  4. To exit the application, press Ctrl+C at the terminal prompt.

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:

  1. If you have not added theming support to the application, open the /src/css folder of your application and edit the application CSS that you maintain. You can add a style class that defines the CSS variable overrides that you intend to apply to certain components.

    For example, to change the height of certain buttons in your application, you can create a style class .demo-jumbo-button and override the JET CSS variable --oj-button-height in the class, like this:

    .demo-jumbo-button { 
      --oj-button-height: 4rem;
      }
    

    And then, in your application HTML, you can style buttons with the class as needed.

    <oj-button class="demo-jumbo-button"></button>
    
  2. Alternatively, if you are theming your application, you can add the style class to the generated _<themeName>.cssvars.settings.scss theme file located in the /src/themes/<themeName>/web folder.

    When you edit the generated file, you must add your style class definitions with JET CSS overrides so they appear at the end of the file, after all JET CSS variables and they must not be contained within :root.

  3. To run your application with live reload enabled, enter ojet serve with the --theme option to specify the CSS that you maintain for your application.
    ojet serve --theme=themeName

    You can omit the --theme option if you set the defaultTheme property in the oraclejetconfig.json file.

  4. Use Oracle JET live reload to immediately observe the effect of any CSS variable overrides.
  5. To exit the application, press Ctrl+C at the terminal prompt.

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 application, 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

html

oj-html

body

oj-body

a

oj-link

h1, h2, h3, h4

oj-header

hr

oj-hr

p

oj-p

ul, ol

oj-ul, oj-ol

Before you begin:

  • Install the theming toolchain and configure a custom theme, as described in Add Custom Theme Support with the JET CLI. The themes folder with custom theme settings files are added to your application source.

To disable JET styling of base HTML tag:

  1. In the /src/themes/themeName/web folder of your application, edit the aggregating themeName.scss file, and comment out the import statement that enables importing all JET component styles.
    // The import statement contains redwood or stable, depending on the value that you
    // supplied to the --basetheme argument when you created the custom theme.
    //@import "oj/all-components/themes/redwood/_oj-all-components.scss";
    or:
    //@import "oj/all-components/themes/stable/_oj-all-components.scss";

    And, then add the import statement to enable compiling with Oracle JET style classes that you can optionally apply to HTML tags.

    @import "oj/all-components/themes/redwood/_oj-all-components-notag.scss";
    or:
    @import "oj/all-components/themes/stable/_oj-all-components-notag.scss";

    This will generate style classes that you can apply to HTML tags, for example <a class=oj-link>.

  2. If your application is already running, you can immediately observe the styling changes. Otherwise, serve your application to enable live reload.
    ojet serve
  3. To exit the application, press Ctrl+C at the terminal prompt.