Theme provider
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: EuiThemeSystemRaw theme values. Calculated values are acceptable.colorMode: EuiThemeColorModeSimply 'light' or 'dark'modify: EuiThemeModificationsOverrides 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.
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: EuiThemeComputedAll the calculated keys including any modificationscolorMode: EuiThemeColorModeSimply 'light' or 'dark'modifications: EuiThemeModificationsOnly 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.