Setup

Installation

EUI is published through NPM as a dependency. To install EUI into an existing project, use the yarn CLI (npm is not supported).

✄𐘗
bash code block:
✄𐘗yarn add @elastic/eui

Note that EUI has several peerDependencies requirements that will also need to be installed when starting with a blank project.

✄𐘗
bash code block:
✄𐘗yarn add @elastic/eui @elastic/eui-theme-borealis @elastic/datemath @emotion/react @emotion/css moment

You can read more about other ways to consume EUI in our wiki.

Supported environments

EUI is designed to work in the following environments:

Environment	Supported?	Details
React 16	❌	Support ended with EUI v106.0.0. Please upgrade to a modern React version.
React 17	✅	Fully supported
React 18	✅	Fully supported (recommended)
React 19	❌	Not supported (plans to introduce support for React 19)
Webpack	✅	Fully supported
Vite/Rollup/Parcel/esbuild	⚠️	Supported with caveats (details)
Strict Mode	❌	Not supported (details)
Server-side Rendering	⚠️	Supported with caveats (details)

If you have questions about your environment or run into issues, please open a GitHub issue or start a discussion.

Setting up your application

EUI uses CSS-in-JS (specifically Emotion) for its styles and theming. As such, we require an <EuiProvider> wrapper around your application in order for various theme-related UI & UX (such as dark/light mode switching) to work as expected.

✄𐘗
tsx code block:
✄𐘗import React from 'react';

import { EuiProvider, EuiText } from '@elastic/eui';

const MyApp = () => (
  <EuiProvider>
    <EuiText><p>Hello World!</p></EuiText>
  </EuiProvider>
);

export default MyApp;

For more configuration options of the provider, see the EuiProvider documentation.

Styling your application

You can build custom components using EUI's theme tokens, consumed via useEuiTheme(). The below example uses Emotion's css prop, but any CSS-in-JS library should be able to interpolate the JS variables.

For more ways to consume EUI's theme, see the EuiThemeProvider documentation.

✄𐘗
tsx code block:
✄𐘗import React from 'react';
import { EuiIcon, EuiCode, EuiText, useEuiTheme } from '@elastic/eui';
import { css } from '@emotion/react';

export default () => {
  const { euiTheme } = useEuiTheme();

  return (
    <EuiText>
      <p>
        <EuiIcon
          type="stopFill"
          size="xxl"
          css={{ color: euiTheme.colors.primary }}
        />{' '}
        This primary color will adjust based on the light or dark theme value
      </p>

      <p
        css={css`
          background: ${euiTheme.colors.lightShade};
          padding: calc(${euiTheme.size.base} * 2);
        `}
      >
        The padding of this box is created using <EuiCode>calc()</EuiCode>{' '}
        because EUI&apos;s theme sizes are string pixel values that are
        calculated off the theme&apos;s <EuiCode>base</EuiCode>
      </p>
    </EuiText>
  );
};

Customizing with classes

For consumers using vanilla or preprocessed CSS, all components allow you to pass a custom className prop, which will be appended onto the component.

Avoid overwriting .eui class names

EUI's class names are not a guaranteed API and are prone to change, which will risk breaking your theme. Target your custom classNames instead.

While EUI's styles are generally low in specificity due to our usage of CSS-in-JS, you may need to ensure that your CSS is defined after ours in your <head>. See EuiProvider's cache customization for more style injection options.

✄𐘗
tsx code block:
✄𐘗import React from 'react';
import { EuiButton } from '@elastic/eui';

const myCustomCSS = `
  .myCustomButton {
    background-color: pink;
  }
`;

export default () => (
  <>
    <style>{myCustomCSS}</style>
    <EuiButton className="myCustomButton">Hello world!</EuiButton>
  </>
);

Customizing the style tokens

EUI can be slightly customized to fit your branding needs by altering the base tokens like color and typography. You can pass a full or partial list of override tokens to the EuiProvider's modify prop.

Touch the least amount of variables possible

By nature, EUI is very rigid. You shouldn't need much to make drastic changes to color. Most themes are less then a dozen variable overwrites in total.

For more examples of the modify prop, see the EuiThemeProvider docs.

✄𐘗
tsx code block:
✄𐘗import React, { FunctionComponent, ReactNode } from 'react';
import { EuiCode, EuiText, EuiThemeProvider, useEuiTheme } from '@elastic/eui';

const Box: FunctionComponent<{ children: ReactNode }> = ({ children }) => {
  const { euiTheme } = useEuiTheme();

  return (
    <EuiText
      css={{
        background: euiTheme.colors.lightShade,
        padding: euiTheme.size.xl,
      }}
    >
      <p>{children}</p>
    </EuiText>
  );
};

export default () => {
  const overrides = {
    colors: {
      LIGHT: { lightShade: '#d3e6df' },
      DARK: { lightShade: '#394c4b' },
    },
  };

  return (
    <div>
      <EuiThemeProvider modify={overrides}>
        <Box>
          The background of this box is using the locally overridden value of{' '}
          <EuiCode>euiTheme.colors.lightShade</EuiCode>
        </Box>
      </EuiThemeProvider>
    </div>
  );
};

Fonts

By default, EUI ships with a font stack that includes some outside, open source fonts. If your system is internet available you can include these by adding the following imports to your SCSS/CSS files, otherwise you'll need to bundle the physical fonts in your build. EUI will drop to System Fonts (which you may prefer) in their absence.

✄𐘗
html code block:
✄𐘗<link
  href="https://fonts.googleapis.com/css2?family=Inter:ital,wght@300;400;500;600;700&family=Roboto+Mono:ital,wght@0,400;0,700;1,400;1,700&display=swap"
  rel="stylesheet"
/>

Or grab all weights, including italics, between 400 and 700 as a variable font.

✄𐘗
html code block:
✄𐘗<link
  href="https://fonts.googleapis.com/css2?family=Inter:slnt,wght@-10,300..700;0,300..700&family=Roboto+Mono:ital,wght@0,400..700;1,400..700&display=swap"
  rel="stylesheet"
/>

Embedding with @font-face

If your application doesn't allow grabbing the font assets from a CDN, you'll need to download and locally provide the font files. You can download the files directly from their source site rsms.me/inter/, then follow the instructions in the provided CSS file for importing. We recommend using the single variable font file and importing with the following settings:

✄𐘗
css code block:
✄𐘗@font-face {
  font-family: 'Inter';
  font-weight: 300 900;
  font-display: swap;
  font-style: oblique 0deg 10deg;
  src: url("Inter.var.woff2") format("woff2");
}

Components, Services and Testing imports

You can import React components from the top-level EUI module.

✄𐘗
tsx code block:
✄𐘗import {
  EuiButton,
  EuiCallOut,
  EuiPanel,
} from '@elastic/eui';

Most services are published from the lib/services directory. Some are published from their module directories in this directory.

✄𐘗
tsx code block:
✄𐘗import { keys } from '@elastic/eui/lib/services';
import { Timer } from '@elastic/eui/lib/services/time';

Test utilities are published from the lib/test directory.

✄𐘗
tsx code block:
✄𐘗import { findTestSubject } from '@elastic/eui/lib/test'; // Enzyme
import { findByTestSubject, render, screen } from '@elastic/eui/lib/test/rtl'; // React Testing Library

Customizing component defaults

While all props can be individually customized via props, some components can have their default props customized globally via EuiProvider's componentDefaults API. Read more in EuiProvider's documentation.

✄𐘗
tsx code block:
✄𐘗<EuiProvider
  componentDefaults={{
    EuiTable: { responsiveBreakpoint: 's', },
    EuiTablePagination: { itemsPerPage: 20, },
    EuiFocusTrap: { crossFrame: true },
    EuiPortal: { insert },
    EuiFlyout: { includeSelectorInFocusTrap: ['.custom-selector', '[data-custom-selector]'], includeFixedHeadersInFocusTrap: false },
    EuiPopover: { repositionOnScroll: true },
    EuiToolTip: { repositionOnScroll: true },
  }}
>
  <App />
</EuiProvider>