Provider

EuiProvider contains all necessary context providers required for full functionality and styling of EUI. A single instance of EuiProvider should exist at the top level of your app, where functionality will flow down the component tree.

Basic setup

For EUI to work correctly, set up EuiProvider at the root of your application:

✄𐘗jsx code block:
✄𐘗import { EuiProvider } from '@elastic/eui';

const MyApp = () => (
  <EuiProvider>
    {/* Content */}
  </EuiProvider>
);

EuiProvider includes global reset and utilities styles and other app-wide contexts, functionality, and configuration options. It should only be instantiated once. This requirement is enforced internally - if another nested instance of EuiProvider is detected, that instance will return early without further processing, and will

warn if configured to do so. Nested instances of EuiThemeProvider, however, are valid.

Theming and global styles

To customize the global theme of your app, use the

theme, colorMode, and modify props (documented in EuiThemeProvider). For instance, it's likely that you will want to implement color mode switching at the top level:

✄𐘗jsx code block:
✄𐘗<EuiProvider colorMode={isDark ? 'dark' : 'light'} />

If you do not wish your app to include EUI's default global reset CSS or utility CSS classes, this is configurable via the globalStyles or utilityClasses props. You can either pass in your own as a React component returning an Emotion Global, or remove them completely by setting the props to false:

✄𐘗jsx code block:
✄𐘗<EuiProvider globalStyles={false} utilityClasses={false} />

`@emotion/cache` customization

The @emotion/cache library provides extra configuration options for EUI's CSS-in-JS behavior:

Browser prefixing: By default, EUI uses CSS browser prefixes based on our supported browsers matrix (latest evergreen only). Should you need to customize this, you can pass in your own prefix plugin via the stylisPlugins option.
Injection location: In the case that your app has its own static stylesheet, Emotion's styles may not be injected into the correct location in the <head>, causing unintentional overrides or unapplied styles. You can use the container option and <meta> tags to achieve this.

✄𐘗html code block:
✄𐘗<!-- index.html -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>My App</title>
    <meta name="eui-style-insert">
    <link name="compiled-css-here" />
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>

✄𐘗jsx code block:
✄𐘗// App.js
import { EuiProvider, euiStylisPrefixer } from '@elastic/eui'

import createCache from '@emotion/cache';

const euiCache = createCache({
  key: 'eui',
  stylisPlugins: [euiStylisPrefixer],
  container: document.querySelector('meta[name="eui-style-insert"]'),
});

euiCache.compat = true;

<EuiProvider cache={euiCache}>
  {/* Content */}
</EuiProvider>

For most applications, the above configuration will be enough to have styles ordered correctly. In advanced more cases, you may use the default, global, and utility properties on the cache prop to further define where specific styles should be inserted. See the props documentation for details.

Any other options available with the createCache API will be respected by EUI. Note that EUI does not include the @emotion/cache library, so you will need to add it to your application dependencies.

Component defaults Beta

Beta status

This functionality is still currently in beta, and the list of components as well as defaults that EUI will be supporting is still under consideration. If you have a component you would like to see added, feel free to discuss that request in EUI's GitHub repo.

All EUI components ship with a set of baseline defaults that can usually be configured via props. For example, EuiFocusTrap defaults to crossFrame={false} - i.e., it does not trap focus between iframes. If you wanted to change that behavior in your app across all instances of EuiFocusTrap, you would be stuck manually passing that prop over and over again, including in higher-level components (like modals, popovers, and flyouts) that utilize focus traps.

EuiProvider allows overriding some component defaults across all component usages globally via the componentDefaults prop like so:

✄𐘗jsx code block:
✄𐘗<EuiProvider
  componentDefaults={{
    EuiTable: { responsiveBreakpoint: 's', },
    EuiTablePagination: { itemsPerPage: 20, },
    EuiFocusTrap: { crossFrame: true },
    EuiPortal: { insert },
  }}
>
  <App />
</EuiProvider>

The above example would override EUI's default table pagination size (50) across all usages of EUI tables and data grids, all EUI focus traps would trap focus even from iframes, and all EUI portals would be inserted at a specified position (instead of the end of the document body).

The current list of supported components and the prop defaults they accept are:


Prop	Description and type	Default value
Prop EuiPortal#	Description and type Provide a global configuration for EuiPortal's default insertion position. Type: `Pick<EuiPortalProps, "insert">`	Default value
Prop EuiFocusTrap#	Description and type Provide a global configuration for EuiFocusTrap's `gapMode` and `crossFrame` props Type: `Pick<EuiFocusTrapProps, "gapMode" \| "crossFrame">`	Default value
Prop EuiTablePagination#	Description and type Provide global settings for EuiTablePagination's props that affect page size / the rows per page selection. These defaults will be inherited all table and grid components that utilize EuiTablePagination. Type: `Pick<EuiTablePaginationProps, "showPerPageOptions" \| "itemsPerPage" \| "itemsPerPageOptions">`	Default value
Prop EuiTable#	Description and type Provide a global configuration for EuiTable's `responsiveBreakpoint` prop. Defaults to `'s'`. Defaults will be inherited by all `EuiBasicTable`s and `EuiInMemoryTable`s. Type: `Pick<EuiTableProps, "responsiveBreakpoint">`	Default value

Enforce usage

For complex applications with multiple mount points or template wrappers, it may be beneficial to enable logging. Doing so will allow you to see warnings for duplicate EuiProviders, as well as when components do not have access to a parent EuiProvider. To enable logging or erroring, use setEuiDevProviderWarning:

✄𐘗jsx code block:
✄𐘗import { setEuiDevProviderWarning } from '@elastic/eui';

setEuiDevProviderWarning('warn');

Examples of apps that would cause warnings:

✄𐘗jsx code block:
✄𐘗const AppWithMissingProvider = () => (
  <EuiPageTemplate>
    {/* Will render, but will warn about missing EuiProvider */}
  </EuiPageTemplate>
);

const App = () => (
  <EuiProvider>
    {/* Content */}
  </EuiProvider>
);

const AppWithDuplicateProvider = () => (
  <EuiProvider>
    {/* Will warn about multiple providers */}
    <App />
  </EuiProvider>
)

setEuiDevProviderWarning accepts three levels:

'log': uses console.log
'warn': uses console.warn
'error': Throws an exception

It also accepts a callback function instead of a default warning level. The warning message string will be passed to your callback, where any custom action can be performed on it. Example usage:

✄𐘗jsx code block:
✄𐘗import { setEuiDevProviderWarning } from '@elastic/eui';

const customWarningHandler = (message: string) => {
  sendWarningToTelemetryService(message);
  console.debug(message);
};

setEuiDevProviderWarning(customWarningHandler);

Props

EuiProvider


Prop	Description and type	Default value
Prop theme#	Description and type Provide a specific EuiTheme; Defaults to EuiThemeBorealis; Pass `null` to remove all theming including global reset Type: `EuiThemeSystem`	Default value
Prop colorMode#	Description and type Allows setting `light` or `dark` mode. Defaults to the user's OS/system setting if undefined. Type: `EuiThemeColorMode`	Default value
Prop highContrastMode#	Description and type Allows enabling a high contrast mode preference for better accessibility. Defaults to the user's OS/system setting if undefined. @see https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-contrast @see https://developer.mozilla.org/en-US/docs/Web/CSS/@media/forced-colors (system only, supercedes this prop) Type: `boolean`	Default value
Prop globalStyles#	Description and type Provide global styles via `@emotion/react` `Global` for your custom theme. Pass `false` to remove the default EUI global styles. Type: `false \| ((params: any) => Element)`	Default value
Prop utilityClasses#	Description and type Provide utility classes. Pass `false` to remove the default EUI utility classes. Type: `false \| ((params: any) => Element)`	Default value
Prop cache#	Description and type Provide a cache configuration(s) from `@emotion/cache`. `default` will encompass all Emotion styles, including consumer defined appliction styles, not handled by nested cache instances. `global` will scope all EUI global and reset styles. `utility` will scope all EUI utility class styles. A cache instance provided as the sole value will function the same as the `default` cache. Type: `EmotionCache \| { default?: EmotionCache; global?: EmotionCache; utility?: EmotionCache; }`	Default value
Prop componentDefaults#	Description and type Allows configuring specified component defaults across all usages, overriding baseline EUI component defaults. Not all components will be supported, and configurable component defaults will be considered on a case-by-case basis. Individual component prop usages will always override these defaults. Type: `EuiComponentDefaults`	Default value
Prop modify#	Description and type Type: `RecursivePartial<EuiThemeShape & T>`	Default value

Basic setup.css-1pgbpvp{-webkit-margin-start:8px;margin-inline-start:8px;opacity:0;}.css-1pgbpvp:focus,.heading:hover .css-1pgbpvp{opacity:1;}