Create a custom theme

A custom theme in ArcGIS Experience Builder can be created by overriding theme variables, providing custom styles, or both. Themes are defined in the client/your-extensions/themes/ directory and consist of a manifest file, optional thumbnail, and style definitions.

Here are the general steps to create a custom theme:

1. Create the theme folder structure

Create a new folder under the client/your-extensions/themes/ directory with the following required files:

• manifest.json: Theme manifest file
  • name: The name of the theme (also its unique identifier)
  • type: Manifest type, must be "theme"
  • isNewTheme: Indicates whether it is a new theme; must be set to true
  • For more properties, refer to ThemeManifest
• thumbnail: Thumbnail image for the theme. Supports PNG and SVG formats. If using SVG, the thumbnail can dynamically change colors according to the theme primary color.

2. Customize theme styles

Once you've created the basic structure, you can customize the theme's appearance:

1. Start by overriding theme variables to adjust colors, fonts, and spacing
2. Optionally, you can override component and global styles for advanced customization if theme variables do not provide enough control.

3. Test your theme

Once you've created the theme, you can test it by navigating to the client directory in your terminal and running:

1
npm start

Once Experience Builder starts, if there are no errors, your new theme card will appear on the Theme panel. You can then apply your theme to an experience to see your customizations.

Customizing theme styles

Experience Builder provides two main approaches for customizing theme styles, each designed for different customization needs:

Method 1: Overriding theme variables (recommended)

This is the simplest and most common method for creating custom themes in Experience Builder. We use the RawThemeOptions interface to define how to override the theme variables.

1
2
3
4
5
6
7
{
  "src": {
    "primary": {
      "color": "green"
    }
  }
}

After starting Experience Builder (as described in step 3), your theme will load with the primary color set to green.

Method 2: Overriding components and global styles

If you need more advanced styling that cannot be achieved via theme options, you can provide custom styles using two approaches:

Option 1: Overriding CSS styles (global styles)

To apply global custom styles, create a style.scss file in your theme folder.

Example:

1
2
3
4
5
6
7
8
body {
  background: #333;
  color: white;
  font-family: Impact;
}
.jimu-button {
  background: red;
}

Option 2: Overriding component styles (scoped styles)

You can use CSS-in-JS with the Emotion library to apply scoped styles to specific components.

Benefits:

• Full access to theme variables and component state
• Styles are scoped to specific components, making them easier to manage
• Dynamic styling based on props and theme values

1
2
3
4
5
6
7
8
//style.ts
import type { ThemeComponentStyleOptions } from 'jimu-theme'

export const Button: ThemeComponentStyleOptions['Button'] = {
  root: () => {
     /* Your custom styles */
  }
}

1
2
3
4
5
export const Button: ThemeComponentStyleOptions['Button'] = {
  root: () =>  `
   /* Your custom styles */
`
}

What's next?

Learn about the different theme development options and how to create and customize themes: