Theme and styles

All components, primitives and templates in Sitecore Search UI Components can be themed following general industry practices. They use commonly accepted CSS properties or variables which add a dynamic nature to an otherwise static language.

Search JS SDK assigns values to the styles at runtime. You do not need a CSS preprocessor like SASS. It is very simple to alter the look and feel of your application by changing the value of a CSS variable.

You have multiple ways to create and apply CSS themes or styles to widget components. Themes are created using CSS variables and can be assigned to the wrapper of widget components or directly to a widget component.

A CSS theme specifies the component's color, font size, font family, among other values. When you use a theme, you can create a consistent look and feel for your application. With a theme, you can customize design aspects to meet specific needs of your business or brand.

In Search, to style widget components, you assign a theme to the styles of the HTML element that wraps JS SDK widget components. Within a component, to further customize a style, you use edit the tokens or variables from the theme object.

You can create a theme by using the createTheme function. This returns a hard copy of the default theme. It contains the styles and the theme object that you can customize.

The createTheme function returns an object with the following:

style - a theme object with every property name prefixed with --sdc. Every property has the same value as in the default theme.
setStyle - a function you can use to apply CSS to any HTML element, by providing it with an HTML element and a style object.
currentTheme - a theme object merged with the default theme.

Add the default theme

The following procedure show how to instantiate the default theme with the createTheme function. The theme is configured with all default values.

To add the default theme to your React application:

In your React application, to use the default theme object, copy and paste the following code block.

RequestResponse

import { createTheme } from '@sitecore-search/ui';

const defaultTheme = createTheme(); // defaultTheme.style - defaultTheme.setStyle - defaultTheme.currentTheme

Add a custom theme

The following procedure describes creating the default theme using the createTheme function.

The following procedure show how to create a custom theme by providing the createTheme function with custom properties.

To add a custom theme to your React :

To match your requirements, update the default theme as shown in the following code block.

RequestResponse

const theme = {
  palette: {
    primary: {
      main: '#F00',
      light: '#EEECFB',
      dark: '#4A37D5',
      contrastText: '#fff',
    },
  }
}

In your React application, to add the custom theme object, copy and paste the following code block.
RequestResponse
```
import { createTheme } from '@sitecore-search/ui';

const customTheme = createTheme( theme );
```
Note

All required theme properties not included in the object supplied to the createTheme function, retain the default theme values.

Apply a theme in HTML

After applying a theme object to an HTML element, all JS SDK widget components with the HTML element get access to all the theme's CSS variables.

To assign a style object to a div element:

Define the style object and assign it as shown in the following code block.

RequestResponse

import { createTheme } from '@sitecore-search/ui';

const { style } = createTheme();
<div style={style}>
  <WidgetsProvider>Content nested in theme.</WidgetsProvider>
</div>

Apply a theme using Javascript

After applying a theme object to an HTML element, all JS SDK widget components with the HTML element get access to all the theme's CSS variables.

To assign the style object to a the body element using Javascript:

Define the style object and assign it as shown in the following code block.

RequestResponse

import { createTheme } from '@sitecore-search/ui';

const defaultTheme = createTheme();
const bodyElement = document.body;
defaultTheme.setStyle(bodyElement, defaultTheme.style);

Edit a component's style using CSS variables

To edit the style of a component using a theme's CSS variables:

Define the component's styles using variables as shown in the following code block.

RequestResponse

import styled from 'styled-components';
import { theme } from '@sitecore-search/ui';

const DivStyled = styled.div`
  background-color: ${theme.vars.palette.primary.main}; // var(--sdc-palette-primary-main)
  color: ${theme.vars.palette.primary.contrastText};
`;

Do you have some feedback for us?

If you have suggestions for improving this article,