Theme provider

Partial component support

EUI is transitioning to a CSS-in-JS solution for theming and requires consuming/customizing global variables in both the Sass and CSS-in-JS methods. To track this effort, subscribe to the Meta ticket.

Theme provider

EUI is in the progress of switching it's core styles processor from Sass to Emotion. To take full advantage of this context layer, wrap the root of your application with a single EuiProvider. While EuiProvider should not be included more than once, you may use multiple nested EuiThemeProviders to customize section-specific or component-specific color modes or theme overrides.

EuiThemeProvider

The context layer that enables theming (including the default theme styles) comes from EuiThemeProvider. EuiThemeProvider accepts three props, all of which have default values and are therefore optional. To use the default EUI theme, no configuration is required.

theme: EuiThemeSystem Raw theme values. Calculated values are acceptable.
colorMode: EuiThemeColorMode Simply 'light' or 'dark'
modify: EuiThemeModifications Overrides and modifications for theme values.

The concept for each prop is explained in subsequent sections. More information on the full shape of an EUI theme, see the Global Values page.

EUI_THEME_AMSTERDAM

colorMode:

LIGHT

Consuming with the React hook

Using the react hook useEuiTheme() makes it very easy to consume the EUI static and computed variables like colors and sizing. It simply passes back an object of the current theme which includes

euiTheme: EuiThemeComputed All the calculated keys including any modifications
colorMode: EuiThemeColorMode Simply 'light' or 'dark'
modifications: EuiThemeModifications Only the modification keys

When consuming the theme's keys like euiTheme.colors.primary, you'll want to pass them via the css property to take advantage of Emotion's compilation.

Consuming with the React HOC

When using inside of a React Component, you can wrap your exported component with withEuiTheme().

Consuming with Emotion's theming

EuiThemeProvider by default sets an Emotion theme context with the results of useEuiTheme(). This is a syntactical sugar convenience that allows you to take advantage of Emotion's styled syntax, or use a function in the css prop.

If you prefer to use or access your own custom Emotion theme, you can completely override EUI's passed theme at any time with your own ThemeProvider.

Simple instance overrides

Usually, you won't need to actually override an EUI theme variable at the instance level. Instead, you'd just create a new variable local to that component. However, if you cannot alter the component that is using the EUI variable then you can wrap that component with the EuiThemeProvider and pass your custom object to modify.

Understanding computed values

The benefit of EUI's theme structure is that it only hard-codes a few color and size variables. The rest are computed values based on this base few. When you update a core variable, this will cascade into the other computed values.

For instance, we compute text variants of our base colors. So locally overriding the colors.primary color will automatically cascade to the colors.primaryText. You can however, directly override computed values as well by passing a custom value to this theme variable.

Creating custom keys

Because of the computed values and possible cascade effects, it may not be advisable to locally override any EUI specific theme variables. Instead, you should append custom keys to the theme.