Use CSS and Themes in Oracle JET Apps

Oracle JET includes the Redwood theme that provides styling across web apps and implements Oracle Redwood Design System. The Redwood theme provides hundreds of custom properties (also called CSS variables) to achieve its look and feel. You can use the Redwood theme as provided, or you can customize the custom properties manually.

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:

In addition, the Redwood theme includes the following CSS:

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": "1.80.5",
    	"defaultTheme": "redwood",
    	"architecture": "mvvm",
    	"generatorVersion": "20.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:

  1. Create the app.

    ojet create my-web-app

    The tooling creates the index.html file in the src folder with an injector token that will load the CSS for the out-of-the-box Redwood theme.

    <!-- This is the main css file for the default theme -->
<!-- injector:theme -->
<!-- endinjector -->

  2. Build a development version of your app.

    ojet build

    The tooling outputs the built app source to the web build folder in the app's root and populates the /web/css/redwood/20.0.0/web folder with the set of available Redwood theme files, including the default theme redwood.css, as well as fonts and images.

    AppRootDir/web/css/redwood/20.0.0/web
  fonts
  images
  redwood-notag-min.css
  redwood-notag.css
  redwood.css
  redwood.min.css

    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 custom themes, as described in Work with Custom Themes and Component Styles.

    Note that index.html in the build output folder by default loads the expanded CSS from redwood.css. To load minified CSS from redwood-min.css, build the app in release mode.

    ojet build --release

  3. Run the app to view the out-of-the-box Redwood theme in the browser.

    ojet serve

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 oj- prefix, none of them is allowed, whether public or private.

Error Icon Here is one example of an overridden Oracle JET class that is not allowed: 

.acme-branding-header .oj-button{
  color: white;
  background: blue;
}

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 . namespace - block - element naming convention for your CSS file.

For example, if you are writing a branding bar that contains a header element for your company acme, then choose acme as the namespace, branding as the block, and header as the element. So, the selector name will be .acme-branding-header . Oracle JET uses dashes in their selector names, but you may use other naming conventions such as Block, Element, Modifier (BEM).

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 branding-header as seen below, your branding header text color will be red.

Client CSS:
.branding-header{color: red}

Your CSS:
.branding-header{background-color: blue}

Using .acme-branding-header rather than just .branding-header will greatly reduce the chance that your client will use a class with the same name.

.acme-branding-header

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.

Error Icon Do not set the font family like this: 

.acme-branding-header {
  font-family: arial;
}

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 html element font size. Oracle JET components rely on REM, which allows your app to adjust to any changes to the underlying CSS font sizes for the themes included with Oracle JET. Likewise, your app can benefit by working with rem units instead of pixels or some other absolute unit. You can use rem units where ever an HTML style can benefit from scalable length units, such as the CSS properties for line-height, width, height, padding, margin, and so on. If you do not want to set a style directly on the html tag, you can reference the oj-html class. 

.acme-branding-header {
  font-size: 1.2rem;
}

Add bi-directional (BIDI) styling support

Oracle JET apps are expected to set dir="rtl" for right-to-left (RTL) languages as described in Set the Text Direction . You can use this setting to support both left-to-right (LTR) and RTL languages in your CSS. To minimize the need to use dir , consider using CSS logical properties in your CSS. 

html:not([dir="rtl"]) .acme-branding-header {
  right: 0; }
html[dir="rtl"] .acme-branding-header {
  left: 0; }

Use oj-hicontrast for high contrast styling

When Oracle JET detects high contrast mode, it places the oj-hicontrast selector on the body element which you can use to change the CSS as needed. See Configure High Contrast Mode . 

.acme-branding-header {
  border: 1px;
}
.oj-hicontrast .acme-branding-header {
  border: 2px;
}

Avoid !important

Avoid the use of !important in your CSS as it makes it problematic to override the value. Where possible, use higher specificity instead. See the Mozilla specificity page for more information.

Warning Icon Avoid using !important . 

.acme-branding-header {
  font-size: 1.2rem !important;
}

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

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.

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:

Icon Font Considerations

Oracle JET uses icon fonts whenever possible because icon fonts have certain advantages over other formats.

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:

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 app 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 app /src/themes folder.

To add theming support:

  1. In your app'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 app 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 app /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, app-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 app 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": "1.80.5",
  "defaultTheme": "myTheme",
      "architecture": "mvvm",
  "generatorVersion": "20.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 app, 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 app, when you build and run the app, 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:

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:

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.

  1. 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.

  2. 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.

  3. 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:

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:

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

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:

To disable JET styling of base HTML tag:

  1. In the /src/themes/themeName/web folder of your app, 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 app is already running, you can immediately observe the styling changes. Otherwise, serve your app to enable live reload.

    ojet serve

  3. To exit the app, press Ctrl+C at the terminal prompt.