Skip to main content
Elastic UI
Elastic UI
Getting startedComponentsPatternsContentData visualization
EUI ChangelogGitHubFigma
  • Setup
  • Theming
  • Accessibility
  • Testing
  • Utilities
    • Accessibility
    • Auto sizer
    • Color palettes
    • Copy
    • CSS utility classes
    • Delay
    • Error boundary
    • Focus trap
    • Highlight and mark
    • HTML ID generator
    • I18n
    • Inner text
    • Mutation observer
    • Outside click detector
    • Overlay mask
    • Portal
    • Pretty duration
    • Provider
    • Resize observer
    • Scroll
    • Text diff
    • Text truncation
    • Window events
  • EUI
  • Utilities
  • Provider

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 EuiBasicTables and EuiInMemoryTables.

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<EuiThemeShapeBase & { overrides?: _EuiThemeOverrides; } & T>
โ†ฆ
Default value
โ†ต
๐˜‚๐˜‚
Edit this page

Previous
Pretty duration
Next
Resize observer
  • Basic setup
  • Theming and global styles
    • @emotion/cache customization
  • Component defaults
  • Enforce usage
  • Props
EUI is dual-licensed under Elastic License 2.0 and Server Side Public License, v 1 | Crafted with โค by Elastic