Getting started

Installation

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

Yarn
pnpm

yarn add @elastic/eui

pnpm add @elastic/eui

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

Yarn
pnpm

yarn add @elastic/eui @elastic/datemath @emotion/react @emotion/css moment prop-types

pnpm add @elastic/eui @elastic/datemath @emotion/react @emotion/css moment prop-types

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

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.

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.

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="stopFilled"
          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's theme sizes are string pixel values that are
        calculated off the theme'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.

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 a full list of global tokens visit Customizing themes. For more examples of the modify prop, see the EuiThemeProvider docs.

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 (
    <EuiThemeProvider modify={overrides}>
      <Box>
        The background of this box is using the locally overridden value of{' '}
        <EuiCode>euiTheme.colors.lightShade</EuiCode>
      </Box>
    </EuiThemeProvider>
  );
};

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.

<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.

<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:

@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.

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.

import { keys } from '@elastic/eui/lib/services';
import { Timer } from '@elastic/eui/lib/services/time';

Test utilities are published from the lib/test directory.

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.

<EuiProvider
  componentDefaults={{
    EuiTablePagination: { itemsPerPage: 20, },
    EuiFocusTrap: { crossFrame: true },
    EuiPortal: { insert },
  }}
>
  <App />
</EuiProvider>