` tag on your page, if it exists. *Tab through the following section to verify the Skip to content button is visible on focus.* ```tsx import React from 'react'; import { EuiSkipLink, EuiText } from '@elastic/eui'; export default () => { return ( ); }; ``` ## Styles helpers import { ClassNamePreview } from './class_name_preview'; import { FunctionPreview } from './function_preview'; import { HookPreview } from './hook_preview'; ### `.euiScreenReaderOnly` className This utility class allows you to apply the screen reader only CSS styles directly to your component. ```tsx

``` ### `euiScreenReaderOnly()` function This function allows you to apply the screen reader only CSS styles directly to your component. ```tsx css` ${euiScreenReaderOnly()} ` ``` ### `useEuiFocusRing(offset?, color?)` hook By default, all interactive elements will inherit the `outline` property from the reset file. However, some instances require adjustment to the `offset` and `color` of this outline. This helper function allows that customization of the focus outline. `offset: 'inset' | 'outset' | 'center' | CSSProperties['outlineOffset'];` `color: CSSProperties['outlineColor'];` ```tsx css` &:focus { ${useEuiFocusRing('center', euiTheme.colors.accent)} } ` ``` ## Props import docgen from '@elastic/eui-docgen/dist/components'; --- ### Packages Website Docs Utilities Color Palettes Index (`packages/website/docs/utilities/color-palettes/index.mdx`) # Color palettes import { ColorPaletteCopyCode, ColorPaletteFlexItem } from './color_palettes_components'; import colorPaletteComponentsSource from '!raw-loader!./color_palettes_components'; EUI provides a base set of color palettes that return an array of hexadecimal color for use in other EUI components or charts. ## Preset qualitative palettes Qualitative palettes are best suited for communicating and comparing discrete data series. EUI recommends using the `euiPaletteColorBlind()` for qualitative and categorical data. This palette is restricted to only 10 colors. However, you can add more groups of 10 which are alternates of the original. This is better than allowing the initial set to loop. These colors are meant to be used as graphics and contrasted against the value of `euiColorEmptyShade` for the current theme. When placing text on top of these colors, use the `euiPaletteColorBlindBehindText()` variant. It is a brightened version of the base palette to create better contrast with text. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## Recommended quantitative palettes Quantitative palettes are best suited for displaying data on a continuum, as in the case of health statuses and large geographic or demographic-based data sets. EUI provides the following common palettes for quantitative data and [charts](../../dataviz/index.mdx). Just pass in the number of steps needed and the function will interpolate between the colors. For usages in React we recommend using the respective palette hooks, e.g. `useEuiPaletteColorBlind`. :::warning The palette for status is the only palette that has proper contrast ratios. When using the other palettes, consider adding another form of the data for screen readers. ::: ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## Custom palettes Use the `colorPalette` service to generate a custom, gradiated palette array of any length from one or more hexadecimal color codes. The third parameter `divergent`, will interpolate between the two halves of the spectrums separately. If a middle point is not provided, it will graduate to light gray. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## Props import docgen from '@elastic/eui-docgen/dist/services/color'; --- ### Packages Website Docs Utilities Focus Trap Index (`packages/website/docs/utilities/focus-trap/index.mdx`) --- keywords: [EuiFocusTrap] --- # Focus trap Use **EuiFocusTrap** to prevent keyboard-initiated focus from leaving a defined area. Temporary flows and UX escapes that occur in components such as [EuiModal](../../components/containers/modal/index.mdx) and [EuiFlyout](../../components/containers/flyout/index.mdx) are prime examples. For components that project content in a React portal, **EuiFocusTrap** will maintain the tab order expected by users. * Use `clickOutsideDisables` to disable the focus trap when the user clicks outside the trap. * Use `noIsolation={false}` when pointer events on outside elements should be disallowed. * Use `crossFrame={true}` when focus should not be allowed on other iframes on the page. import FormExample from './form_compressed'; import formCompressedSource from '!raw-loader!./form_compressed'; ```tsx interactive import React, { useState } from 'react'; import { EuiBadge, EuiButton, EuiFocusTrap, EuiPanel, EuiSpacer, EuiText, } from '@elastic/eui'; import FormExample from './form_compressed'; export default () => { const [isDisabled, changeDisabled] = useState(true); const toggleDisabled = () => changeDisabled(!isDisabled); return (

Trap is {isDisabled ? 'disabled' : 'enabled'} {`${!isDisabled ? 'Disable' : 'Enable'} Focus Trap`} The button below is not focusable by keyboard as long as the focus trap is enabled. {}}>External Focusable Element

); }; ``` ## Props import docgen from '@elastic/eui-docgen/dist/components/focus_trap'; --- ### Packages Website Docs Utilities Scroll Index (`packages/website/docs/utilities/scroll/index.mdx`) # Scroll import { css } from '@emotion/react'; import { Example } from '@site/src/components'; import { EuiFlexGroup, EuiFlexItem, EuiPanel, EuiProvider, EuiText, logicalCSS, logicalCSSWithFallback, useEuiOverflowScroll, useEuiScrollBar } from '@elastic/eui'; import { ScrollContent } from './scroll_content'; import { HorizontalScrollClassNamePreview, HorizontalScrollHookPreview, ScrollBarClassNamePreview, ScrollBarHookPreview, VerticalScrollClassNamePreview, VerticalScrollHookPreview } from './previews'; :::warning Scrollable regions must be focusable, promoted to region and with the right aria-label To ensure keyboard-only users have access to the scrollable regions, the optimal solution is to apply `tabIndex="0"` to the region. **Learn more about the `scrollable-region-focusable` rule at Deque**. ::: ## Scroll bar style ### `.eui-scrollBar` className Use this utility class to style the browser's scrollbar in a minimal aesthetic. This is best used on small, inner-page contents like panels wherever you have `overflow: auto`. ```tsx

``` ### `useEuiScrollBar()` hook Use this style function to style the browser's scrollbar in a minimal aesthetic. This is best used on small, inner-page contents like panels. All parameters are optional and default to specific global settings. ```tsx css` ${useEuiScrollBar()} ` ``` ## Vertical (scroll-y) These utilities allow for quickly applying vertical scrolling to a container. They also automatically apply the minimal scroll bar styles as well. If you do not want your content to stretch to `100%` height, you will need to manually add a `height` (or `max-height`) to the container. The `WithShadows` variants are primarily used in modals and flyouts and masks the edges to indicate there is more content. When using these variants, you may want to add a small amount padding to the top and bottom of your content so the mask doesn't overlay it. ### `.eui-yScroll` className Quick utility class for adding vertical scrolling to a container. ```tsx

``` ### `useEuiOverflowScroll('y')` hook Styles hook for adding vertical scrolling to a container. To mask the top and bottom of the scrolled content, indicating visually that there is more content below, pass in true to the second parameter `mask`. `useEuiOverflowScroll('y', true);` ```tsx css` ${useEuiOverflowScroll('y', true)} ` ``` ## Horizontal (scroll-x) The horizontal equivalent should be used sparingly and usually only in full-height layouts or a grid of items. When using the `WithShadows` variant, you may want to add a small amount padding to the sides of your content so the mask doesn't overlay it. ### `.eui-xScroll` className Quick utility class for adding horizontal scrolling to a container. ```tsx

``` ### `useEuiOverflowScroll('x')` hook Styles hook for adding horizontal scrolling to a container. To mask the top and bottom of the scrolled content, indicating visually that there is more content below, pass in true to the second parameter `mask`. `useEuiOverflowScroll('x', true);` ```tsx css` ${useEuiOverflowScroll('x', true)} ` ``` ## Full height layout ### `.eui-fullHeight` className Quick utility for expanding the height of the element to its parents dimensions. Use it to stretch each nested element until the one that applies scroll. Works on both flex and non-flex elements.

Orbiting this at a distance of roughly ninety-two million miles is an utterly insignificant little blue green planet whose ape-descended life forms are so amazingly primitive that they still think digital watches are a pretty neat idea.

```tsx ``` ### `euiFullHeight()` function Emotion mixin for adding full height scrolling to a container or flex child. It applies `height: 100%; overflow: hidden;` but also adds `flex: 1 1 auto;` for use within `flex` containers. ```tsx css` ${euiFullHeight()} ` ``` --- ### Packages Website Docs Utilities Window Events Index (`packages/website/docs/utilities/window-events/index.mdx`) # Window events import { ModalExample } from './modal_example'; import modalExampleSource from '!raw-loader!./modal_example'; ## Basic example: closing a modal on escape Use an **EuiWindowEvent** to safely and declaratively manage adding and auto-removing event listeners to the `window`. This is preferable to setting up your own window event listeners because it will remove old listeners when your component unmounts, preventing you from accidentally leaving them around forever. This modal example registers a listener on the `keydown` event and listens for ESC key presses, which closes the open modal. ```tsx interactive import React from 'react'; import { EuiModal, EuiModalBody, EuiModalHeader, EuiModalHeaderTitle, } from '@elastic/eui'; import { ModalExample } from './modal_example'; const BasicModal = ({ onClose }) => ( Example modal

This modal closes when you press ESC, using a window event listener.

); export default () => ; ``` ## Avoiding event conflicts :::warning Be careful with global listeners Since window event listeners are global, they can conflict with other event listeners if you aren't careful. ::: The safest and best way to avoid these conflicts is to use `event.stopPropagation()` at the lowest, most specific level where you are responding to a DOM event. This will prevent the event from bubbling up to the window, and the **EuiWindowEvent** listener will never be triggered, avoiding the conflict. ```tsx interactive import React, { useState } from 'react'; import { EuiModal, EuiModalBody, EuiModalHeader, EuiModalHeaderTitle, EuiFieldText, EuiSpacer, keys, } from '@elastic/eui'; import { ModalExample } from './modal_example'; const ConflictModal = (props) => { const [inputValue, setInputValue] = useState(''); const updateInputValue = (e) => { setInputValue(e.target.value); }; const clearInputValueOnEscape = (event) => { if (event.key === keys.ESCAPE) { setInputValue(''); event.stopPropagation(); } }; return ( Example modal

While typing in this field, ESC will clear the field.

Otherwise, the event bubbles up to the window and ESC closes the modal.

); }; export default () => ( ); ``` ## Tracking mouse position For some DOM events, you have to listen on the window. One example of this is tracking mouse position. Below, when you click the toggle switch, your mouse position is tracked. When you toggle off, tracking stops. If you were manually attaching window listeners, you might forget to remove the listener and be silently responding to mouse events in the background for the life of your app. The **EuiWindowEvent** component manages that unmount/unregister process for you. ```tsx interactive import React, { useState } from 'react'; import { EuiSwitch, EuiDescriptionList, EuiSpacer, EuiWindowEvent, } from '@elastic/eui'; export default () => { const [tracking, setTracking] = useState(false); const [coordinates, setCoordinates] = useState({}); const onSwitchChange = () => { setTracking(!tracking); }; const onMouseMove = ({ clientX, clientY }) => { setCoordinates({ clientX, clientY }); }; const listItems = [ { title: 'Position X', description: coordinates.clientX || '??', }, { title: 'Position Y', description: coordinates.clientY || '??', }, ]; return (

{tracking ? ( ) : null}

); }; ``` ## Props import docgen from '@elastic/eui-docgen/dist/services/window_event'; --- ### Packages Website Docs Components Containers Flyout Index (`packages/website/docs/components/containers/flyout/index.mdx`) --- keywords: [EuiFlyout, EuiFlyoutBody, EuiFlyoutHeader, EuiFlyoutFooter, EuiFlyoutMenu] --- # Flyout **EuiFlyout** is a fixed position panel that pops in from the side of the window. It should be used to reveal more detailed contextual information or to provide complex forms without losing the user's current state. It is a good alternative to [modals](../modal/index.mdx) when the action is not transient. Like modals, you control the visibility of the flyout using your own state management, but **EuiFlyout** requires an `onClose` handler for it's internal dismiss buttons. ## Component :::accessibility Accessibility requirement Use `aria-labelledby={headingId}` to ensure the flyout is announced to screen readers. ::: ```tsx interactive import React, { useState } from 'react'; import { EuiFlyout, EuiFlyoutBody, EuiFlyoutHeader, EuiButton, EuiText, EuiTitle, EuiCodeBlock, useGeneratedHtmlId, } from '@elastic/eui'; export default () => { const [isFlyoutVisible, setIsFlyoutVisible] = useState(false); const simpleFlyoutTitleId = useGeneratedHtmlId({ prefix: 'simpleFlyoutTitle', }); let flyout; const htmlCode = `

... `; if (isFlyoutVisible) { flyout = ( setIsFlyoutVisible(false)} aria-labelledby={simpleFlyoutTitleId} >

A typical flyout

For consistency across the many flyouts, please utilize the following code for implementing the flyout with a header.

{htmlCode} ); } return (

setIsFlyoutVisible(true)}> Show flyout {flyout}

); }; ``` ## Usage ### Accessing flyout elements Pass a React `ref` to **EuiFlyoutHeader** or **EuiFlyoutFooter** to access its root `div`. On **EuiFlyout**, `ref` points to the flyout panel and `scrollContainerRef` points to the outer `.euiFlyout__content` container wrapping the header, body, and footer. **EuiFlyoutBody** has a separate `scrollContainerRef` pointing to its inner overflow container. Normally, the body's container is what scrolls. The outer container scrolls only when using **EuiFlyoutBody** and the header, body, and footer exceed the viewport height (usually on short screens). To respond to every scroll, attach to both containers. ### More complicated flyout This component also comes with related child components for ease of creating headers, footers and scrolling body content. **EuiFlyoutHeader** and **EuiFlyoutFooter** are pinned to the top and bottom of the flyout, respectively, to allow for always visible navigation and actions. The **EuiFlyoutBody** component will then automatically overflow. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### Sizing Flyouts come in three predefined `size`s of `'s' | 'm' | 'l'`, which define the width **relative to the window size** with a minimum width defined in pixels. You can otherwise supply your own fixed width in number or string format. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### Padding All the inner flyout components inherit their padding from the wrapping **EuiFlyout** component. This ensures that all the horizontal edges line up no matter the `paddingSize`. When using the `"none"` size, you will need to accommodate your content with some other way of creating distance to the edges of the flyout. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### Banners To highlight some information at the top of a flyout, you can pass an [EuiCallOut](../../display/callout.mdx) to the `banner` prop available in **EuiFlyoutBody** and its layout will adjust appropriately. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### Without ownFocus Like modals, you will usually want to obscure the page content beneath with `ownFocus` which wraps the flyout with an [EuiOverlayMask](../../../utilities/overlay-mask.mdx) . However, there are use-cases where flyouts present more information or controls, but need to maintain the interactions of the page content. By setting `ownFocus={false}`, the underlying page content will be visible and clickable. ```tsx interactive import React, { useState } from 'react'; import { EuiFlyout, EuiFlyoutHeader, EuiFlyoutBody, EuiButton, EuiText, EuiTitle, useGeneratedHtmlId, } from '@elastic/eui'; export default () => { const [isFlyoutVisible, setIsFlyoutVisible] = useState(false); const closeFlyout = () => setIsFlyoutVisible(false); const toggleFlyout = () => setIsFlyoutVisible((isVisible) => !isVisible); const withoutFocusFlyoutTitleId = useGeneratedHtmlId({ prefix: 'withoutFocusFlyoutTitle', }); let flyout; if (isFlyoutVisible) { flyout = (

A flyout without ownFocus

The page contents is still interactive though screen reader users will find themselves still within the bounds of the flyout.

); } return (

Toggle flyout {flyout}

); }; ``` ### Understanding max-width By default, flyouts will continue to grow with the width of the window. To stop this growth at an ideal width, set `maxWidth` to `true`, or pass your own custom size. :::warning Note that there are some caveats to providing a maxWidth that is smaller than the minWidth. ::: ``` /* Detailed source-code truncated for AI context efficiency. */ ``` import { Example } from '@site/src/components'; ### Focus management `EuiFlyout` used with `type="overlay"` manages focus for keyboard navigation and accessibility. This ensures users can navigate modal content effectively, especially those using screen readers or keyboard-only navigation. When a `EuiFlyout` is used, it will automatically: 1. Move focus to the flyout when opened 2. Trap focus inside the flyout while open 3. Return focus to the trigger element when closed #### Manual return focus control Use `focusTrapProps` to customize the focus behavior: ```tsx { // Return true to use default behavior (focus triggerElement) // Return false to prevent default behavior if (customElement.current) { customElement.current.focus(); return false; } return true; }, }} /> ``` :::warning Manually return focus when the trigger element is removed If the trigger element is removed from the DOM before the flyout closes, focus will be "lost" to the document body. In this case, manually return focus to an appropriate element using `focusTrapProps.returnFocus`. ::: ### Push flyout import PushFlyout from './_flyout_push.mdx'; ### Resizable flyout import ResizableFlyout from './_flyout_resizable.mdx'; ### Container-relative positioning By default, flyouts use `position: fixed` and are positioned relative to the viewport. The optional `container` prop allows you to scope a flyout to a specific region of the page instead. When a `container` element is provided, the flyout's bounding rect is used to compute inline positioning styles that visually constrain the flyout within the container's bounds. The flyout remains in `document.body` with `position: fixed` — no DOM mutations are applied to the container (except push-mode padding). This is useful when flyouts should not overlap application chrome such as side navigation or toolbars. For example, in Kibana the default container is the application content area so that flyouts stay within the app region. ```tsx const [containerEl, setContainerEl] = useState(null);

{isFlyoutVisible && ( {/* ... */} )}

``` Resize clamping and responsive breakpoints use the container's width as the reference instead of the viewport width. The container element is treated as read-only — it is not modified by the flyout except for push-mode padding (`paddingInlineEnd` or `paddingInlineStart`) when a push flyout is open. #### Child flyout inheritance Child flyouts automatically inherit the `container` from the parent flyout's context. There is no need to pass the prop explicitly to child flyouts. To use the document body as the reference container for a child (overriding an inherited container), pass `container={null}`. ```mdx-code-block import { EuiBetaBadge } from '@elastic/eui'; ``` ### Flyout menu {#flyout-menu} import FlyoutMenu from './_flyout_menu.mdx'; ## Guidelines import SessionManagement from './_session_management.mdx'; ## Props import docgen from '@elastic/eui-docgen/dist/components/flyout'; import docgenFlyoutMenuTypes from '@elastic/eui-docgen/dist/components/flyout/flyout_menu/types.docgen.json'; --- ### Packages Website Docs Components Containers Modal Index (`packages/website/docs/components/containers/modal/index.mdx`) --- slug: /containers/modal id: containers_modal keywords: [EuiModal, EuiModalBody, EuiModalFooter, EuiModalHeader, EuiModalHeaderTitle, EuiConfirmModal] --- # Modal A modal is best for focusing the user's attention on a **small** amount of content and prompting a decision, such as a [confirmation](#confirm-modal). Use it to temporarily interrupt the current task and block interaction with the content below. Each **EuiModal** needs a specific set of nested child components. You can omit some if needed, but do not change their order. :::tip Modal vs flyout If your modal content is complex or takes a long time to complete, consider using an [EuiFlyout](../flyout/index.mdx) instead. ::: ## Components :::accessibility Accessibility requirement Use `aria-labelledby={modalTitleId}` to ensure the modal is announced to screen readers. ::: ### Default Modals use an **EuiOverlayMask** to obscure content beneath. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` import { Example } from '@site/src/components'; ### Focus management `EuiModal` manages focus for keyboard navigation and accessibility. This ensures users can navigate modal content effectively, especially those using screen readers or keyboard-only navigation. When a `EuiModal` is used, it will automatically: 1. Move focus to the modal when opened 2. Trap focus inside the modal while open 3. Return focus to the trigger element when closed #### Manual return focus control Use `focusTrapProps` to customize the focus behavior: ```tsx { // Return true to use default behavior (focus triggerElement) // Return false to prevent default behavior if (customElement.current) { customElement.current.focus(); return false; } return true; }, }} /> ``` :::warning Manually return focus when the trigger element is removed If the trigger element is removed from the DOM before the modal closes, focus will be "lost" to the document body. In this case, manually return focus to an appropriate element using `focusTrapProps.returnFocus`. ::: ### Confirm modal import ConfirmModal from './_confirm_modal.mdx'; ## Usage import Patterns from './_patterns.mdx'; ## Guidelines import Guidelines from './_guidelines.mdx'; ## Props import docgen from '@elastic/eui-docgen/dist/components/modal'; --- ### Packages Website Docs Components Containers Panel Index (`packages/website/docs/components/containers/panel/index.mdx`) --- keywords: [EuiPanel, EuiSplitPanel] --- # Panel **EuiPanel** is a building block component. Use it as a layout helper for containing content. It is also commonly used as a base for other larger components like [EuiPage](../../templates/page-template/index.mdx), [EuiPopover](../popover.mdx) and [EuiCard](../card.mdx). ## Component ### Default Panels default to a flat bordered look (`hasBorder=true`, `hasShadow=false`). Use shadow only when you need elevation. ```tsx interactive import React from 'react'; import { EuiPanel } from '@elastic/eui'; export default () => ( Default panel ); ``` ### Split import SplitPanel from './_split_panel.mdx'; ## Usage ### Padding The most basic use is to simply add padding around your content. The preferred padding options are `none`, `s`, `m` (default) and `l`. ```tsx interactive import React from 'react'; import { EuiPanel, EuiCode, EuiSpacer } from '@elastic/eui'; export default () => (

paddingSize="none" paddingSize="s" paddingSize="m" (default) paddingSize="l"

); ``` ### Shadow and border By default, **EuiPanel** is flat with `hasBorder=true` on and `hasShadow=false`. Use `hasShadow` when you need elevation. Be mindful of not using too many [nested panels](#guidelines) with these settings. :::warning Certain allowed combinations of shadow, border, and color depend on the current theme. For instance, only plain or transparent panels can have a border and/or shadow. The default theme doesn't allow combining the `hasBorder` option with `hasShadow`. ::: ```tsx interactive import React from 'react'; import { EuiPanel, EuiCode, EuiSpacer } from '@elastic/eui'; export default () => { return (

Default (hasBorder, no shadow) {'hasBorder={false} hasShadow'}

); }; ``` ### Colors and corners Use `color` to add background shading to your panel and provide an additional helpful aesthetic to your container in context. Be mindful to use color sparingly. You can also remove the rounded corners depending on the placement of your panel with `borderRadius="none"` Passing `color="transparent"` can give you a quick empty box simply for adding padding to all sides. ```tsx interactive import React from 'react'; import { EuiPanel, EuiSpacer } from '@elastic/eui'; export default () => (

I am a simple shaded box

I am a transparent box simply for padding

); ``` ### Growing height Using **EuiPanel** in an [EuiFlexItem](../../layout/flex/item.mdx#panels-grow-vertically-to-fill-flex-items) will always grow its height to match. This is great for rows of panels. However, you can also turn this feature off by setting `grow={false}`. ```tsx interactive import React from 'react'; import { EuiPanel, EuiFlexGroup, EuiFlexItem, EuiText } from '@elastic/eui'; export default () => (

I am some panel content...
...
...
whose content is tall

I am some panel content... whose content will grow

I am some panel content... whose content did not grow

); ``` ## Guidelines import Guidelines from './_guidelines.mdx'; ## Props import docgen from '@elastic/eui-docgen/dist/components/panel'; import PropTableSplitPanel from './_split_panel_props'; --- ### Packages Website Docs Components Containers Tabs Index (`packages/website/docs/components/containers/tabs/index.mdx`) --- keywords: [EuiTabs, EuiTab] --- # Tabs Use tabs to organize related but unique content for a single idea or subject. Tabs show and hide content using **in-page** navigation UI. **EuiTabs** is a wrapping component that requires **EuiTab** components as direct children. You control the displayed contents and current state through props on EuiTab like `isSelected` and `onClick`. Use the `prepend` and `append` tab props to add content before and after the tab label respectively. ## Component ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## Usage ### Tab sizes **EuiTabs** allow a `size` prop. In general you should always use the default (medium) size. The small size is best for when placing inside popovers or other small containers. Reserve using the large size for when using as primary page navigation, like inside of [EuiPageHeader](../../layout/page-header.mdx). You can also use the `expand` prop to evenly stretch each tab horizontally. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### Bottom border The `bottomBorder` helps to separate the tab group from the content below and is on by default. However, some components like [flyouts](../../containers/flyout/index.mdx) already provide borders which can act as the divider. In this case you can turn the border off with `bottomBorder={false}`. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### Tabbed content **EuiTabbedContent** makes it easier to associate tabs with content based on the selected tab. Use the `initialSelectedTab` prop to specify which tab to initially select. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### Controlled tabbed content You can also use the `selectedTab` and `onTabClick` props to take complete control over tab selection. This can be useful if you want to change tabs based on user interaction with another part of the UI. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## Guidelines import Guidelines from './_guidelines.mdx'; ## Props import docgen from '@elastic/eui-docgen/dist/components/tabs'; --- ### Packages Website Docs Components Display Badge Index (`packages/website/docs/components/display/badge/index.mdx`) --- keywords: [EuiBadge, EuiBetaBadge, EuiNotificationBadge] --- # Badge **EuiBadge** highlights key pieces of information. While badges will space themselves automatically when used repeatedly, it's best practice to wrap them in an **EuiBadgeGroup**. This ensures they wrap properly when space is limited (as shown below). ## Components ### Default ```tsx interactive import React, { useState } from 'react'; import { EuiBadge, } from '@elastic/eui'; export default () => Default badge; ``` ### Notification badge import NotificationBadge from './_notification_badge.mdx'; ### Beta badge import BetaBadge from './_beta_badge.mdx'; ## Usage ### Color options Badge colors can be configured with the [`color` prop](#EuiBadge-prop-color) and the related [`fill` prop](#EuiBadge-prop-fill). When a named color like `primary` is passed to the `color` prop, the `fill` prop determines whether the badge will use filled (more intense) or non-filled (less intense) colors. By default, all badges use non-filled colors. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### Badge with Icon Badges can use icons on the left and right (default) sides. ```tsx interactive import React from 'react'; import { EuiBadge } from '@elastic/eui'; export default () => (

Hollow Default Primary with an app icon

); ``` ### Badge with onClick events Badges can have `onClick` events applied to the badge itself or the icon within the badge. The latter option is useful for when you might use badges in other components (like a tag system with autocomplete where you need close events). :::note `onClick` with `iconOnClick` When providing both these click handlers, **EuiBadge** must alter the contents so that it does not contain nested button tags. Please make note that if you provide props other than those explicit to **EuiBadge**, they will always be applied to the main `button` tag which may be inside of the outer most tag. ::: ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### Badge for health status Badges can work as health status indicators in places where there are a lot of repeated statuses, e.g. in tables. ```tsx interactive import React from 'react'; import { EuiBadge, EuiFlexGroup, EuiFlexItem } from '@elastic/eui'; export default () => ( Healthy Warning Critical Unknown ); ``` ### Badge with href Badges can also be made to render anchor tags by passing an `href`. ```tsx interactive import React from 'react'; import { EuiBadge, EuiFlexGroup, EuiFlexItem } from '@elastic/eui'; export default () => ( badge as an anchor anchor with target specified {}} iconOnClickAriaLabel="Example of onClick event for icon within the anchor" > anchor with an icon and iconOnClick disabled anchor badge ); ``` ### Badge groups and truncation Badges, like buttons, will only every be a single line of text. This means text will not wrap, but be truncated if the badge's width reaches that of its parent's. For this reason, badges also auto-apply the inner text of the badge to the `title` attribute of the element to provide default browser tooltips with the full badge text. To ensure proper wrapping, truncation and spacing of multiple badges, it is advisable to wrap them in a **EuiBadgeGroup**. ```tsx interactive import React from 'react'; import { EuiBadge, EuiPanel, EuiBadgeGroup } from '@elastic/eui'; export default () => ( Badge with simple text being truncated Badge with icon being truncated {}} onClickAriaLabel="Click this badge to..."> Badge with onClick being truncated {}} iconOnClickAriaLabel="Click this icon to..." > Badge with iconOnClick being truncated {}} onClickAriaLabel="Click this badge to..." iconOnClick={() => {}} iconOnClickAriaLabel="Click this icon to..." > Badge with both onClicks being truncated ); ``` ## Guidelines import Guidelines from './_guidelines.mdx'; ## Props import docgen from '@elastic/eui-docgen/dist/components/badge'; --- ### Packages Website Docs Components Display Comment List Index (`packages/website/docs/components/display/comment-list/index.mdx`) --- keywords: [EuiCommentList, EuiComment] --- # Comment list The **EuiCommentList** is a timeline component built on top of [EuiTimeline](../timeline.mdx). It allows you to display comments or logged actions that either a user or a system has performed. :::accessibility Accessibility recommendation Provide a descriptive `aria-label` or the ID of an external label to the `aria-labelledby` prop of the **EuiCommentList**. A `timelineAvatarAriaLabel` should be provided for every **EuiComment** with or without a `timelineAvatar` as `IconType`. ::: ## Basic comment list Use **EuiCommentList** to display a list of **EuiComments**. Pass an array of **EuiComment** objects and **EuiCommentList** will generate a comment thread. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## Comment The **EuiComment** is flexible and adapts the design according to the props passed. import { CommentListProps, CommentListStyle } from './comment_list_props.tsx'; {children} `} /> 1. `timelineAvatar`: Shows an avatar that should indicate who is the author of the comment. To customize, pass a `string` as an `EuiIcon['type']` or an [EuiAvatar](../avatar.mdx). Use in conjunction with `timelineAvatarAriaLabel` to pass an aria label to the avatar. If no avatar is provided, it will default to an avatar with a `user` icon. 2. `eventIcon`: Icon that shows before the username. Use in conjunction with `eventIconAriaLabel` to pass an aria label to the event icon. 3. `username`: Author of the comment. 4. `event`: Describes the event that took place. 5. `timestamp`: Time of occurrence of the event. 6. `actions`: Custom actions that the user can perform from the comment's header. When having multiple actions, consider grouping them in a nested menu system using a [EuiPopover](../../containers/popover.mdx) with a [EuiContextMenu](../../navigation/context-menu.mdx). 7. `children`: A user message or any custom component. The following demo shows how you can combine different props to create different types of comments events like a regular, update, update with a danger background and a custom one. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## Timeline avatar The timeline icon is a very important part of the comment: * By default, each **EuiComment** shows an avatar with the `user` icon. A `timelineAvatarAriaLabel`should be provided when using this default option. * You can customize your avatar by passing to the `timelineAvatar` any of the icon types that [EuiIcon](../icons/index.mdx) supports. The icon will show inside a `subdued` avatar. Consider this option when showing a system update. Providing a `timelineAvatarAriaLabel` is recommended. * You can further customize the timeline icon by passing to the `timelineAvatar` a [EuiAvatar](../avatar.mdx). ```tsx interactive import React from 'react'; import { EuiCommentList, EuiComment, EuiCode, EuiText, EuiAvatar, } from '@elastic/eui'; export default () => (

The avatar initials is generated from the username{' '} prop.

The timelineAvatar is using a{' '} dot icon. } /> } >

The timelineAvatar is using a custom{' '} EuiAvatar.

); ``` ## Comment event actions There are scenarios where you might want to allow the user to perform `actions` related to each comment. Some common `actions` include: editing, deleting, sharing and copying. To add custom `actions` to a comment, use the `actions`prop. These will be placed to the right of the metadata in the comment's header. We recommend using a [EuiButtonIcon](../../navigation/buttons/button.mdx#icon) to trigger an action. When having multiple actions, consider grouping them in a nested menu system using a [EuiPopover](../../containers/popover.mdx) with a [EuiContextMenu](../../navigation/context-menu.mdx). ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## A comment system The below example uses a list of **EuiComments**, a [EuiMarkdownEditor](../../editors-and-syntax/markdown/editor.mdx), and a [**EuiMarkdownFormat**](../../editors-and-syntax/markdown/format.mdx) to create a simple comment system. * Each comment renders in a **EuiComment**. * We use the **EuiMarkdownEditor** to post the `EuiComment.children`. This means the content uses Markdown. * When the new **EuiComment** is posted, we use the **EuiMarkdownFormat** to wrap the `EuiComment.children` and render the Markdown correctly. When dealing with asynchronous events like posting a message we recommend setting the **EuiMarkdownEditor** to a `readOnly` state and the "Add comment" **EuiButton** to a `isLoading` state. This will ensure users understand that the content cannot be changed while the comment is being submitted. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## Props import docgen from '@elastic/eui-docgen/dist/components/comment_list'; --- ### Packages Website Docs Components Display Empty Prompt Index (`packages/website/docs/components/display/empty-prompt/index.mdx`) --- keywords: [EuiEmptyPrompt] --- # Empty prompt import illustrationUrl from '!url-loader!../../../../static/images/empty_prompt/illustration.svg'; import illustrationSource from '!raw-loader!../../../../static/images/empty_prompt/illustration.svg'; The **EuiEmptyPrompt** is the building block to create an empty state. You can use it as a placeholder for any type of empty content. They are especially helpful for replacing entire pages or parts of a product that contain no content. ## Component While no one piece of content is required, each **EuiEmptyPrompt** should contain at least a `title` (wrapped in an HTML heading element) and/or a `description`. They usually contain one or more `actions` that promotes the primary call-to-actions. You can also provide a `footer` to direct users towards making informed decisions. ```tsx interactive import React from 'react'; import { EuiEmptyPrompt, EuiButton, EuiTitle, EuiLink } from '@elastic/eui'; export default () => ( Start adding cases} body={

Add a new case or change your filter settings.

} actions={ Add a case } footer={ <>

Want to learn more?

Read the docs } /> ); ``` ## Usage ### Less content, more actions You can remove parts of the prompt to simplify it. You can also provide an array of multiple actions. Be sure to list primary actions first and secondary actions as empty buttons. ```tsx interactive import React from 'react'; import { EuiEmptyPrompt, EuiButton, EuiButtonEmpty } from '@elastic/eui'; export default () => ( Upgrade your license to use Machine Learning} actions={[ Upgrade , Start a trial, ]} /> ); ``` ### Panel options The **EuiEmptyPrompt** is wrapped by [EuiPanel](../../containers/panel/index.mdx). By default, the panel is set to `transparent` but you can customize other panel options like `color`, `hasBorder` and `paddingSize`. Changing the `color` prop will also attempt to adjust the `iconColor` and `footer` color. Read the [usage guidelines](#guidelines) to better understand when to use certain panel props. ```tsx interactive import React, { FunctionComponent } from 'react'; import { EuiEmptyPrompt, EuiButton, EuiTitle, EuiLink, EuiEmptyPromptProps, } from '@elastic/eui'; export default ({ color }: { color: EuiEmptyPromptProps['color'] }) => { return ( Start adding cases} color={color} body={

Add a new case or change your filter settings.

} actions={ Add a case } footer={ <>

Want to learn more?

Read the docs } /> ); }; ``` ### Title sizes and icon colors Other customization options include changing the`titleSize` to any of the [EuiTitle sizes](../title.mdx) and `iconColor`. When using an application or solution logo as the `iconType`, you can reset to the multi-tone colors with `iconColor="default"` ```tsx interactive import React from 'react'; import { EuiEmptyPrompt, EuiButton } from '@elastic/eui'; export default () => ( Start adding cases} titleSize="xs" body={

Add a new case or change your filter settings.

} actions={ Add a case } /> ); ``` ### Loading and error prompts Empty prompts can also be used to emulate loading and error states, by utilizing the same patterns. For **loading** states, instead of passing a `iconType`, you can provide a custom `icon` and pass in one of our [loading components](../loading.mdx). ```tsx interactive import React from 'react'; import { EuiEmptyPrompt, EuiLoadingLogo } from '@elastic/eui'; export default () => ( } title={

Loading Dashboards

} /> ); ``` For **error** states, you can simply set the `color` to `danger`. ```tsx interactive import React from 'react'; import { EuiEmptyPrompt } from '@elastic/eui'; export default () => ( Unable to load your dashboards} body={

There was an error loading the Dashboard application. Contact your administrator for help.

} /> ); ``` ### Layout You can supply a `layout` of either `"horizontal"` or `"vertical"` with the default being `vertical`. When creating empty states we want the content to be short and straight to the point. So most of the time, the `vertical` layout is enough. All the content will be center aligned and this type of text alignment only works with small content. When you have longer body text with multiple calls to action, you can use the `horizontal` layout. This layout works best when you can provide a larger graphic like an illustration as the `icon`. For consistency, we recommend providing the illustration using a [EuiImage](../image.mdx) with `size="fullWidth"`. ```tsx import React from 'react'; import { EuiEmptyPrompt, EuiButton, EuiTitle, EuiLink, EuiImage, } from '@elastic/eui'; import illustration from './illustration.svg'; export default () => { return ( <> } title={

Create your first visualization

} layout="horizontal" color="plain" body={ <>

There are no visualizations to display. This tool allows you to create a wide range of charts, graphs, maps, and other graphics.

The visualizations you create can be easily shared with your peers.

} actions={ Create visualization } footer={ <> Want to learn more? {' '} Read the docs } /> ); }; ``` ### More types of empty states **EuiEmptyPrompt** can be used for more than just **empty** pages. The following example showcases different types of empty states that you can create with the **EuiEmptyPrompt**. For a full list see the [usage guidelines](#guidelines). import MultipleTypes from './_multiple_types'; ### Using in a page template When using a **EuiEmptyPrompt** in a [EuiPageTemplate](../../templates/page-template/index.mdx), we recommend using the namespaced component so the template can determine which how to display the empty prompt based on the rest of the template configuration. The following example shows the usage of the [EuiPageTemplate.EmptyPrompt](../../templates/page-template/index.mdx#empty-pages-or-content) namespaced component. ```tsx import React from 'react'; import { EuiPageTemplate, EuiButton, EuiTitle, EuiLink, EuiImage, } from '@elastic/eui'; import illustration from './illustration.svg'; export default () => ( Create your first visualization} icon={} color="plain" layout="horizontal" body={ <>

There are no visualizations to display. This tool allows you to create a wide range of charts, graphs, maps, and other graphics.

The visualizations you create can be easily shared with your peers.

} actions={ Create visualization } footer={ <> Want to learn more? {' '} Read the docs } /> ); ``` You can then tie multiple types of empty states together to create a seamless loading to empty or loading to error experience. The following example shows how to incorporate these states with [EuiPageTemplate.EmptyPrompt](../../templates/page-template/index.mdx#empty-pages-or-content). {/* setting a fixed `height` to avoid jumps on the page as the state changes */} (

{children}

)}> ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## Guidelines import Guidelines from './_guidelines.mdx'; ## Props import docgen from '@elastic/eui-docgen/dist/components/empty_prompt'; --- ### Packages Website Docs Components Display Icons Index (`packages/website/docs/components/display/icons/index.mdx`) --- keywords: [EuiIcon] --- # Icons import { EuiCodeBlock, EuiSpacer, EuiSplitPanel, EuiToken } from '@elastic/eui'; **EuiIcon** is a handy component for using our custom glyphs and logos. The `type` prop accepts either an enumerated name from one of the sets below, a location to a custom SVG asset, or a React Element. ## Component ```tsx interactive import React from 'react'; import { EuiIcon } from '@elastic/eui'; export default () => ; ``` :::accessibility Accessibility recommendation If possible, provide a descriptive title based on the icon use. If no title is provided, the icon is considered purely decorative, and it will default to `aria-hidden=true`. ::: ## All icons ### Glyphs Glyphs are small, monochromatic icons that typically should always use the default size of `size="m"`. They are named according to their appearance or the action they represent. For example, `star`, `play`, etc. If you would like to contribute to our growing list of glyphs, you can follow [these guidelines](https://github.com/elastic/eui/blob/main/wiki/contributing-to-eui/developing/creating-icons.md). import { IconSearch } from '@site/src/components/display/icons'; import { typeToPathMapDocsGlyphIconTypes as iconTypes, typeToPathMapSynonyms as iconSynonyms, } from '../../../../../eui/src/components/icon/icon_map'; ```tsx import React from 'react'; import { css } from '@emotion/react'; import { EuiCodeBlock, EuiSpacer } from '@elastic/eui'; import { IconSearch } from '@site/src/components/display/icons'; import { typeToPathMapDocsGlyphIconTypes as iconTypes, typeToPathMapSynonyms as iconSynonyms, } from '../../../../../eui/src/components/icon/icon_map'; export default () => (

{''}

); ``` ### Elastic logos These logos are restricted in use to Elastic products or when referencing Elastic products. They are multi-color with some internal paths having a class of `.euiIcon__fillNegative` to handle flipping colors for dark mode. The only other colors most of them support are ghost and text which turn them into a solid shape. import { typeToPathMapDocsLogoIconTypes as iconTypesLogos } from '../../../../../eui/src/components/icon/icon_map'; ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### Apps App logos are logos for Elastic Apps, and can contain multiple colors. Normally the Elastic Design team creates those icons. They are not meant to be used outside of Elastic, because they represent our apps. App logos are usually displayed at `32x32` or above and can contain multiple colors. Our set of App Icons are a subset of what the [Elastic Design team provides](https://brand.elastic.co/302f66895/p/031452-icons). If you require an icon from that set which EUI does not currently provide, please open a [Feature Request](https://github.com/elastic/eui/issues) for the EUI team to add it. import { typeToPathMapDocsAppIconTypes as iconTypesApps } from '../../../../../eui/src/components/icon/icon_map'; ```tsx import React from 'react'; import { css } from '@emotion/react'; import { EuiCodeBlock, EuiSpacer } from '@elastic/eui'; import { IconSearch } from '@site/src/components/display/icons'; import { typeToPathMapDocsAppIconTypes as iconTypes } from '../../../../../eui/src/components/icon/icon_map'; export default () => (

{''}

); ``` ### Machine learning icons Machine learning has some specific icons for job creation. Again, these are made for `32x32`. import { typeToPathMapDocsMlIconTypes as iconTypesML } from '../../../../../eui/src/components/icon/icon_map'; ```tsx import React from 'react'; import { css } from '@emotion/react'; import { EuiCodeBlock, EuiSpacer } from '@elastic/eui'; import { IconSearch } from '@site/src/components/display/icons'; import { typeToPathMapDocsMlIconTypes as iconTypes } from '../../../../../eui/src/components/icon/icon_map'; export default () => (

{''}

); ``` ## Usage ### Sizes Use the `size` prop to automatically size your icons. Medium is the default, and will output a `16x16` icon. import { iconSizes, iconSizesText } from './icon_sizes'; import iconSizeSource from '!raw-loader!./icon_sizes'; ```tsx import React from 'react'; import { css } from '@emotion/react'; import { EuiCodeBlock, EuiSpacer, EuiFlexGrid, EuiFlexItem, EuiCopy, EuiPanel, EuiIcon } from '@elastic/eui'; import { iconSizes, iconSizesText } from './icon_sizes'; export default () => (

{''} {iconSizes.map((size, index) => ( {(copy) => ( {' '} {iconSizesText[index]} )} ))}

); ``` ### Colors The default behavior of icons is to inherit from the text color. You can use the `color` prop to assign a custom color which accepts a named color from our palette or a valid [CSS color data type](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) which will be passed down through the inline-style `fill` property. **We recommend relying on the EUI named color palette** unless the custom color is initiated by the user (like as a graph color). Two-tone icons, like our app style icons, will behave similarly to normal glyphs when provided a specific color by applying the color to **all** the shapes within. You can force the icon to match the parent's text color by passing `color="inherit"` to the icon. import { iconColors } from './icon_colors.ts' import iconColorsSource from '!raw-loader!./icon_colors'; ```tsx import React from 'react'; import { css } from '@emotion/react'; import { EuiCodeBlock, EuiSpacer, EuiFlexGrid, EuiFlexItem, EuiCopy, EuiPanel, EuiIcon, EuiThemeProvider } from '@elastic/eui'; import { iconColors } from './icon_colors'; export default () => (

{''} {iconColors.map((color) => ( {(copy) => { const panel = ( {' '} {color} ); return color === 'ghost' ? {panel} : panel; }} ))}

); ``` ### Custom SVGs The `type` prop can accept a valid enum, string or React SVG Element. When using a custom SVG, please make sure it sits on a square canvas and preferably utilizes one of EUI's sizes (`16x16` or `32x32`). When using custom SVGs for simple glyphs, **remove all fill attributes** on the SVG and utilize the CSS helpers if you have complex logos that need to work with theming. :::warning Important considerations when importing SVGs as components When importing an SVG as a component like `import { ReactComponent as ReactLogo } from './logo.svg';`, keep in mind that the component will not support the `title` prop. The `title` prop is designed to only work with our icons or SVGs imported as images or passed as a Data URL. So, if you're importing your SVG as a component, be sure to use an`aria-label` instead of a `title` prop to enhance accessibility and avoid potential issues. ::: import customSvg from '!url-loader!./custom.svg'; import customSvgSource from '!raw-loader!./custom.svg'; ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### Using icons outside of React EUI publishes raw SVG files and a JSON manifest for consumers who need to use icons outside of the React component layer - for example, to generate canvas images, produce CSS background images at build time, or render icons in non-React environments. **Individual SVG files** are available under `@elastic/eui/dist/svgs/`. For example: ``` @elastic/eui/dist/svgs/accessibility.svg @elastic/eui/dist/svgs/tokens/tokenAlias.svg ``` **JSON manifest** (`@elastic/eui/dist/eui-icons.json`) maps icon filename stems to their raw SVG content strings: ```js import icons from ‘@elastic/eui/dist/eui-icons.json’; const svg = icons[‘accessibility’]; // plain glyph const tokenSvg = icons[‘tokens/tokenAlias’]; // token icon ``` :::warning Server-side and build-time use only `eui-icons.json` is intended for **server-side or build-time use** (e.g. Node.js scripts, SSR, canvas rasterization). Importing it in client-side code will inline all SVG strings into your JavaScript bundle. ::: ## Tokens Tokens are most commonly used to visually signify field or code types. An **EuiToken** accepts any valid **EuiIcon** as its `iconType` property. However, icons designed specifically for use in the **EuiToken** are prefixed with "token" in their name and have pre-defined styles. import { typeToPathMapDocsTokenIconTypes as iconTypesTokens } from '../../../../../eui/src/components/icon/icon_map'; ```tsx import React from 'react'; import { css } from '@emotion/react'; import { EuiCodeBlock, EuiSpacer, EuiToken } from '@elastic/eui'; import { IconSearch } from '@site/src/components/display/icons'; import { typeToPathMapDocsTokenIconTypes as iconTypes } from '../../../../../eui/src/components/icon/icon_map'; export default () => (

{''} ( )} />

); ``` ### Custom tokens By default, an `iconType` with the token prefix (i.e. those listed above) will have predefined styles. However, any valid `iconType` can be passed and, in either case, the `shape`, `size`, `color`, and `fill` can be customized. {''} {''} {''} {''} {''} ## Props import docgen from '@elastic/eui-docgen/dist/components/icon'; --- ### Packages Website Docs Components Display Illustrations Index (`packages/website/docs/components/display/illustrations/index.mdx`) --- keywords: [EuiIllustration, illustrations, svg] --- # Illustrations **EuiIllustration** renders theme-adaptive SVGs. Each illustration ships a `light` and a `dark` variant and the component inlines the one that matches the current theme. SVGs are sourced from [`@elastic/eui-illustrations`](https://github.com/elastic/eui/tree/main/packages/illustrations), a standalone package that is **independently versioned and published** from `@elastic/eui`. This means the catalog can grow and change without an `@elastic/eui` release. ## Component Pass an illustration asset to the `type` prop. The component picks the correct color-mode variant automatically, so try toggling the theme in the top toolbar. import { illustrations } from '@elastic/eui-illustrations'; ```tsx import React from 'react'; import { EuiIllustration } from '@elastic/eui'; import { dashboard } from '@elastic/eui-illustrations'; import { css } from '@emotion/react'; export default () => (

); ``` :::accessibility Accessibility recommendation The accessible label defaults to the illustration's `title`. Provide a more specific `alt` when the illustration conveys meaning or pass `alt=""` to mark it as purely decorative (it will be hidden from assistive technology). ::: ## All illustrations Search the full catalog exported from `@elastic/eui-illustrations`. Select an illustration to reveal the code. import { IllustrationGallery } from './illustration_gallery'; ## Props import docgen from '@elastic/eui-docgen/dist/components/illustration'; --- ### Packages Website Docs Components Display Toast Index (`packages/website/docs/components/display/toast/index.mdx`) --- keywords: [EuiToast, EuiGlobalToastList] --- # Toast import previewWrapper from './_preview_wrapper'; **EuiToast** allows for small notes that appear in the bottom right of the screen. They should be used for ephemeral, live actions (think **save complete** or **something just finished right now**). They should not be used for historical actions (**your report built 30 minutes ago**). This means that a user should never be greeted with toasts when starting a session. Toasts should be brief and avoid long paragraphs of text or titling. ## Component ```tsx interactive import React from 'react'; import { EuiToast } from '@elastic/eui'; export default () => ( {}} /> ); ``` ## Usage ### Toast list ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### Colors Each `color` variant displays a specific visual type toast and renders by default a corresponding icon. * Use `primary` for general information. * Use `success` to let the user know that something completed successfully. Show a success message when the program detects that **something completed successfully**. * Use `warning` to warn the user against decisions they might regret. Show a warning message when the program detects that **something is not behaving right, but it didn't cause any termination.** * Use `danger` to let the user know that something went wrong. For example if you want to communicate an error. You should show an error message when the issue is **terminal, this doesn't always mean that the operation stops completely, but the task is not complete**. If you need to use a custom icon, use the `iconType` prop to override it. ```tsx interactive import React from 'react'; import { EuiToast, EuiSpacer } from '@elastic/eui'; export default () => ( <> ); ``` ### Actions Use `actionProps` to add a primary and an optional secondary action. A standalone secondary action without a primary is not supported. ```tsx interactive import React from 'react'; import { EuiToast } from '@elastic/eui'; export default () => ( ); ``` ### Countdown animation To show a countdown animation on top of the toast to indicate the remaining time until it dismisses, use `animationMs`. ```tsx interactive import React, { useEffect, useState } from 'react'; import { EuiToast, EuiButton, EuiFlexGroup } from '@elastic/eui'; const ANIMATION_MS = 6000; export default () => { const [animationMs, setAnimationMs] = useState(undefined); useEffect(() => { setAnimationMs(ANIMATION_MS); }, []); return ( setAnimationMs(animationMs != null ? undefined : ANIMATION_MS)} > {animationMs != null ? 'Reset animation' : 'Start animation'} {}} /> ); }; ``` ## Guidelines import Guidelines from './_guidelines.mdx'; ## Props import docgen from '@elastic/eui-docgen/dist/components/toast'; --- ### Packages Website Docs Components Display Tour Index (`packages/website/docs/components/display/tour/index.mdx`) --- keywords: [EuiTour, EuiTourStep, useEuiTour] --- # Tour The tour components provided by EUI allow for a flexible and customizable way to showcase items on a page in an ordered manner by augmenting existing elements on the page without altering functionality. :::note Examples on this page use `localStorage` to persist state. ::: ## Usage ### Wrap target element The **EuiTourStep** component is the base for building a feature tour or an individual popover for onboarding. All content and actions including titles, headings, and buttons are customizable via props. ```tsx interactive import React, { useState } from 'react'; import { EuiButtonEmpty, EuiFieldText, EuiText, EuiSpacer, EuiTourStep } from '@elastic/eui'; export default () => { const [isOpen, setIsOpen] = useState(false); const beginTour = () => { setIsOpen(true); }; return (

Begin tour

The tour step content.

} isStepOpen={isOpen} minWidth={300} onFinish={() => setIsOpen(false)} step={1} stepsTotal={1} title="Title of the current step" subtitle="Title of the full tour (optional)" anchorPosition="rightCenter" zIndex={1} >

); }; ``` ### Anchor to DOM element Instead of wrapping the target element, use the `anchor` prop to specify a DOM node. Accepted values include an HTML element reference, a function returning an HTML element, or a CSS selector string such as `anchor="#anchorTarget"`. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### Guided tour Users proceed through tour steps without needing to complete actions on the underlying page. In this scenario, consider showing both **Close tour** and **Next** buttons. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### Standalone steps Each **EuiTourStep** can be configured independently via props. In this case, each component is stateless and needs to be paired with some form of state management for navigation. The later examples showcase other ways to handle state management via **useEuiTour** and **EuiTour**. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### useEuiTour hook The **useEuiTour** hook provides minimal state management using a predefined React reducer. Pass an array of steps consisting of accepted props, and an object of global configuration. The result is a full configuration object for each step, a set of reducer actions to perform state changes, and an up-to-date state object derived from the internal reducer. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### EuiTour render prop component The **EuiTour** render prop component provides minimal state management. An alternative to the **useEuiTour** hook, **EuiTour** can be used for React class components and use cases with a single wrapping component. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### Tour demo A complete tour set in a more realistic application UI. Unlike other examples on this page, the demo does not use `localStorage` to persist state. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## Guidelines import Guidelines from './_guidelines.mdx'; ## Props import docgen from '@elastic/eui-docgen/dist/components/tour'; --- ### Packages Website Docs Components Forms Selection Overview (`packages/website/docs/components/forms/selection/overview.mdx`) --- sidebar_position: 1 --- # Component comparison ```mdx-code-block import { EuiIconTip, EuiTable, EuiTableRow, EuiTableHeader, EuiTableBody, EuiTableRowCell, EuiTableHeaderCell } from '@elastic/eui'; ``` EUI currently offers over 4 ways to select an option from a list (6 including checkboxes and radios). Choosing the right selection component may seem tricky at first - with so many similar options, it can feel overwhelming figuring out which component to use. This comprehensive guide will help you decide which component to use and when, including detailed explanations and comparisons for each component. ## Summary When choosing a selection component, consider these key factors: - **Number of options**: small sets (\<7) work well with radio/checkbox groups, medium sets (\<12) with [EuiSelect](./basic-select.mdx), and larger sets need search functionality. - **Selection type**: single vs. multiple selection requirements. - **Display needs**: whether you need custom option rendering or simple text options. - **User input**: whether users should be able to add custom values. - **Accessibility**: native components ([EuiSelect](./basic-select.mdx), radio/checkbox groups) are generally more accessible. - **Visual layout**: horizontal pills ([EuiComboBox](./combo-box.mdx)) vs. vertical lists ([EuiSelectable](./selectable.mdx)). For most use cases, start with the simpler native components ([EuiSelect](./basic-select.mdx), [EuiRadioGroup](./radio-and-radio-group.mdx#radio-group), [EuiCheckboxGroup](./checkbox-and-checkbox-group.mdx#checkbox-group)) and only move to more complex components when you need their specific features. ## Which selection component should I use? The following decision tree will help you choose the right component based on your specific needs. ### Single selection - When you have a small set of options (\<7) and all options are equally important in terms of visibility, use [EuiRadioGroup](./radio-and-radio-group.mdx#radio-group). - When you have a small set of options (\<12) and only the current selected option has UI importance, reach for [EuiSelect](./basic-select.mdx) first when possible, over other more complex selection components. - **EuiSelect** renders a basic HTML ``. ### Event handlers All event handlers should take the form `onEvent` and accurately describe when it will be called. e.g. `onClick` indicates the handler is called when the component is clicked, but if there is more granularity the handler should reflect that with `onItemClick`, `onRowClick`, etc. ## Common and required props Try to leverage the `children` prop wherever possible. This will create a simpler more uniform API throughout our components. We also [require some props](../../../packages/eui/src/test/required_props.ts) to be supported by all components, as reflected in our tests; for example, `className`. These are easily added via the `CommonProps` mentioned above. ## Pass-through props To give the consumer as much flexibility as possible we use the destructuring assignment to pull expected props out of the received props and pass `...rest` to one of the elements in the `render()` method. This element is typically the root element, though in rare cases another element makes more sense. The main benefit behind this practice is that the consumer can specify any of the [DOM attributes](https://reactjs.org/docs/dom-elements.html) supported by React, including custom ones with the `data-` prefix. In Typescript, it makes sense to then extend the props of that element when declaring the component's type. EUI also provides a shortlist of commonly used props like `className`, `aria-label`, and `data-test-subj` that you should extend as well. ```jsx import { HTMLAttributes, FunctionComponent } from 'react'; import { CommonProps } from '../common'; export type EuiMegaMenuProps = HTMLAttributes & CommonProps & { color: EuiMegaMenuColor; isDisabled?: boolean; /* ... */ }; export const EuiMegaMenu: FunctionComponent = ({ children, className, color = 'primary', size, className, isDisabled = false, ...rest }) => { // Anything else specified by the consumer will be applied to the div as a DOM attribute. return (

{/* ... */}

); } ``` The component's TypeScript definition needs to properly include the target DOM element's props. A `Foo` component that passes `...rest` through to a `button` element would have the `HTMLButtonElement` props interface. ```ts // passes extra props to a button interface FooProps extends ButtonHTMLAttributes { title: string } ``` ## Props documentation from Typescript We use [react-docgen-typescript](https://github.com/styleguidist/react-docgen-typescript/) combined with some custom [props filters](../../../scripts/babel/react-docgen-typescript.js) to automatically generate our Props tab/table from our Typescript component types. > :warning: [react-docgen-typescript currently has a bug](https://github.com/styleguidist/react-docgen-typescript/issues/395) that does not correctly generate props for all components if a file has multiple components that set a `displayName`. To avoid this bug and broken props tables, keep your component files atomic / limited to 1 major component per file. --- ### Contributing To Eui Developing Refs (`wiki/contributing-to-eui/developing/refs.md`) # Component refs Components should always accept a `ref` prop which should typically pass back the primary underlying native DOM element to the `ref` callback. However, more complex components (e.g., `EuiDataGrid` and `EuiMarkdownEditor`) may instead pass back [a ref of imperative APIs](#providing-custom-or-additional-data) as a way to control said component. ## forwardRef React's [`forwardRef`](https://reactjs.org/docs/forwarding-refs.html) should be used to provide access to the component's outermost element. We impose two additional requirements when using `forwardRef`: 1. Use `forwardRef` instead of `React.forwardRef`, otherwise [react-docgen-typescript](https://github.com/styleguidist/react-docgen-typescript/) does not understand it and the component's props table will error in our documentation 2. The resulting component must have a `displayName`, which is useful when the component is included in a snapshot or when inspected in devtools. There is an eslint rule which checks for this. ### Simple forward/pass-through ```tsx import React, { forwardRef } from 'react'; interface MyComponentProps {...} export const MyComponent = forwardRef< HTMLDivElement, // type of element or component the ref will be passed to MyComponentProps // what properties apart from `ref` the component accepts >( ( { destructure, props, here, ...rest }, ref ) => { return (

...

); } ); MyComponent.displayName = 'MyComponent'; ``` ### Combining with additional refs Sometimes an element needs to have 2+ refs passed to it, for example a component interacts with the same element the forwarded ref needs to be given to. For this EUI provides a `useCombinedRefs` hook: ```tsx import React, { forwardRef, createRef } from 'react'; import { useCombinedRefs } from '../../services'; interface MyComponentProps {...} export const MyComponent = forwardRef< HTMLDivElement, // type of element or component the ref will be passed to MyComponentProps // what properties apart from `ref` the component accepts >( ( { destructure, props, here, ...rest }, ref ) => { const localRef = useRef(null); const combinedRefs = useCombinedRefs([ref, localRef]); return (

...

); } ); MyComponent.displayName = 'MyComponent'; ``` ## Providing custom or additional data Rarely, a component's ref needs to be something other than a DOM element, or provide additional information. In these cases, React's `useImperativeHandle` can be used to provide a custom object as the ref's value. For example, **EuiMarkdownEditor**'s ref includes both its textarea element and the `replaceNode` method to interact with the abstract syntax tree. https://github.com/elastic/eui/blob/v31.10.0/src/components/markdown_editor/markdown_editor.tsx#L331 ```tsx import React, { useImperativeHandle } from 'react'; export const EuiMarkdownEditor = forwardRef< EuiMarkdownEditorRef, EuiMarkdownEditorProps >( (props, ref) => { ... // combines the textarea element & `replaceNode` into a single object, which is then passed back to the forwarded `ref` useImperativeHandle( ref, () => ({ textarea: textareaRef.current, replaceNode }), [replaceNode] ); ... } ); ``` --- ### Contributing To Eui Developing Writing Styles With Emotion (`wiki/contributing-to-eui/developing/writing-styles-with-emotion.md`) # Writing styles with Emotion EUI uses [`Emotion`](https://emotion.sh/) when writing CSS-in-JS styles. A general knowledge of writing CSS is enough in most cases, but there are some JavaScript-related differences that can result in unintended output. Similarly, there are feaures that don't exist in CSS of which we like to take advantage. ## File patterns ```ts /* {component name}.styles.ts */ import { css } from '@emotion/react'; import { UseEuiTheme } from '../../services'; // Always start the object with the first key being the name of the component export const euiComponentNameStyles = ({ euiTheme }: UseEuiTheme) => { return { euiComponentName: css` color: ${euiTheme.colors.textPrimary}; `, }; }; ``` ---

🎉 ProTip: VS Code snippet

To make generating component boilerplate just a little bit easier, you can add the following block to a global or local snippet file in VS Code. Once saved, you'll be able to generate the boilerplate by typing `euisc` `tab`. Learn how to add snippets in VS Code: ```json "euiStyledComponent": { "prefix": "euisc", "body": [ "/*", "* Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one", "* or more contributor license agreements. Licensed under the Elastic License", "* 2.0 and the Server Side Public License, v 1; you may not use this file except", "* in compliance with, at your election, the Elastic License 2.0 or the Server", "* Side Public License, v 1.", "*/", "", "import { css } from '@emotion/react';", "import {", " euiFontSize,", " logicalCSS,", "} from '../../global_styling';", "import { UseEuiTheme } from '../../services';", "", "export const ${1:componentName}Styles = ({ euiTheme }: UseEuiTheme) => {", " return {", " ${1:componentName}: css`", " ${2:property}: tomato;", " `", " };", "};" ], "description": "EUI styled component" } ```

--- ```tsx /* {component name}.tsx */ import { useEuiTheme } from '../../services'; import { euiComponentNameStyles } from './{component name}.styles.ts'; export const EuiComponent = () => { const theme = useEuiTheme(); const styles = euiComponentNameStyles(theme); const cssStyles = [styles.euiComponentName] return (

); }; ``` ## CSS-aligned props If a prop/value pair maps 1:1 to the CSS property: value, pass the value straight through. We encounter this scenario when it is apparent that a given css property is core to configuring a component, and it doesn't make sense to use an abstraction. ```tsx position?: CSSProperties['position']; const cssStyles = [ { position } ]; ``` ## Component props that enable styles ### Building an array of styles Use an array inside of the `css` prop for optimal style composition and class name generation. This is relevant even if only a single style object is passed. _examples from [avatar.tsx](https://github.com/elastic/eui/blob/main/packages/eui/src/components/avatar/avatar.tsx)_ ```tsx export const EuiAvatar: FunctionComponent = ({...}) => { // access the theme and compute avatar's styles const euiTheme = useEuiTheme(); const styles = euiAvatarStyles(euiTheme); ... // build the styles array const cssStyles = [ styles.euiAvatar, // base styles styles[size], // styles associated with the `size` prop's value styles[type], // styles associated with the `type` prop's value // optional styles isPlain && styles.plain, isSubdued && styles.subdued, isDisabled && styles.isDisabled, ]; ... // pass the styles array to the `css` prop of the target element return (

) } ``` ### If a prop's value renders no styles A. If it's necessary to still know the prop value while debugging, create an empty css`` map for that value ```tsx paddingSize = 'none'; const euiComponentStyles = ({ none: css`` }) ``` B. If it's mostly just an empty default state, check for that prop before grabbing the css value ```tsx paddingSize = 'none'; const cssStyles = [ paddingSize === 'none' ? undefined : styles[paddingSize] ] ``` ## Style maps When building styles based on an array of possible prop values, you'll want to establish the array of values first in the component file then use that array to create your prop values and your styles map. ```tsx export const SIZES = ['s', 'm', 'l', 'xl', 'xxl'] as const; export type EuiComponentNameSize = typeof SIZES[number]; export type EuiComponentNameProps = CommonProps & { size?: EuiComponentNameSize; }; export const EuiComponentName: FunctionComponent = ({...}) => { const euiTheme = useEuiTheme(); const styles = euiComponentNameStyles(euiTheme); const cssStyles = [styles.euiComponentName, styles[size]]; return (

) } ``` ```ts const componentSizes: { [size in EuiComponentNameSize]: _EuiThemeSize; } = { s: 'm', m: 'base', l: 'l', xl: 'xl', xxl: 'xxl', }; export const euiComponentNameStyles = ({ euiTheme }: UseEuiTheme) => ({ euiComponentName: css``, // Sizes s: css` width: ${euiTheme.size[componentSizes.s]}; height: ${euiTheme.size[componentSizes.s]}; `, m: css` width: ${euiTheme.size[componentSizes.m]}; height: ${euiTheme.size[componentSizes.m]}; `, ...etc }); ``` ## Style helpers EUI components often have style variants that use a similar patterns. In these cases, consider creating a helper function to create repetitive styles. ```ts const _componentSize = ({ size, fontSize, }: { size: string; fontSize: string; }) => { return ` width: ${size}; height: ${size}; line-height: ${size}; font-size: ${fontSize}; `; }; ``` The helper function can then be used in the exported style block: ```ts export const euiComponentNameStyles = ({ euiTheme }: UseEuiTheme) => ({ // Sizes s: css( _componentSize({ size: euiTheme.size.l, fontSize: euiTheme.size.m, }) ), m: css( _componentSize({ size: euiTheme.size.xl, fontSize: `calc(${euiTheme.size.base} * 0.9)`, }) ), l: css( _componentSize({ size: euiTheme.size.xxl, fontSize: `calc(${euiTheme.size.l} * 0.8)`, }) ), }); ``` Note that the helper function returns a string literal instead of a `css` method from `@emotion/react`. This reduces the serialization work at runtime and makes the helper more flexible (e.g., could be used with a `style` attribute). Also note that the `css` method from `@emotion/react` can be [called as a normal function](https://emotion.sh/docs/@emotion/css#css) instead of as a template literal. ## Conditional styles Styles can be added conditionally based on environment variables, such as the active theme, using nested string template literals. ```ts ` color: colors.primary; background: ${colorMode === 'light' ? 'white' : 'black'`} ` ``` Although possible in some contexts, it is not recommended to "shortcut" logic using the `&&` operator. Use ternary statements to avoid `undefined` statments from entering the compiled code. ```ts `${font.body.letterSpacing ? `letter-spacing: ${font.body.letterSpacing}` : ''`}` ``` ## Duplicate styles When writing styles for prop enums (e.g. sizing enums: `s`, `m`, `l`, etc.), some props may have duplicated styles between two values. If the duplicated styles are just a line or two, repeating the CSS is not particularly problematic. However, if the repeated CSS starts to get lengthy or unintuitive, consider using a [JS getter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get) to return duplicate styles, for example: ```ts export const euiComponentNameStyles = ({ euiTheme }: UseEuiTheme) => ({ // Sizes s: css` /* lengthy or complex styles */ `, get m() { // Same as `s` return this.s; }, l: css` /* different styles */ `, }); ``` For a production example of this scenario, see [EuiStep's styles](https://github.com/elastic/eui/blob/ea535de773703ec225804228aa3aa68d18d84dc5/src/components/steps/step.styles.ts#L86-L105). ## Child selectors Most components also contain child elements that have their own styles. If you have just a few child elements, consider having them in the same function. ```ts export const euiComponentNameStyles = ({ euiTheme }: UseEuiTheme) => ({ euiComponentName: css``, euiComponentName__child: css`` }); ``` ```tsx export const EuiComponentName: FunctionComponent = ({...}) => { const euiTheme = useEuiTheme(); const styles = euiComponentNameStyles(euiTheme); const cssStyles = [styles.euiComponentName]; const cssChildStyles = [styles.euiComponentName__child]; return (

) } ``` If you have multiple child elements, consider grouping them in different theme functions to keep things tidy. Keep them within a single `styles.ts` file if they exist in the same `.tsx` file. ```ts export const euiComponentNameStyles = ({ euiTheme }: UseEuiTheme) => ({ euiComponentName: css`` }); export const euiComponentNameHeaderStyles = ({ euiTheme }: UseEuiTheme) => ({ euiComponentName__header: css``, euiComponentName__headerIcon: css``, euiComponentName__headerButton: css`` }); export const euiComponentNameFooterStyles = ({ euiTheme }: UseEuiTheme) => ({ euiComponentName__footer: css`` }); ``` ```tsx export const EuiComponentName: FunctionComponent = ({...}) => { const euiTheme = useEuiTheme(); const styles = euiComponentNameStyles(euiTheme); const cssStyles = [styles.euiComponentName]; const headerStyles = euiComponentNameHeaderStyles(euiTheme); const cssHeaderStyles = [headerStyles.euiComponentName__header]; const cssHeaderIconStyles = [headerStyles.euiComponentName__headerIcon]; const cssHeaderButtonStyles = [headerStyles.euiComponentName__headerButton]; const footerStyles = euiComponentNameFooterStyles(euiTheme); const cssFooterStyles = [footerStyles.euiComponentName__footer]; return (

) } ``` ### Merging child element css with spread operators Please keep in mind that while Emotion will automatically merge `css` props for **top** level components, it will **not** do so for any child elements. Take for example the following component: ```tsx // This example is incorrect! export const EuiComponentName: FunctionComponent = ({ iconProps, ...rest }) => { const euiTheme = useEuiTheme(); const styles = euiComponentNameStyles(euiTheme); const cssStyles = [styles.euiComponentName]; const cssIconStyles = [styles.euiComponentName__icon]; return ( // This will merge Emotion CSS as expected

) } ``` If a consumer passes ``, Emotion will automatically correctly combine EUI's component styles and the passed custom styles. **However**, if a consumer passes ``, Emotion will **not** handle merging in the child `css` props and will simply override/ignore whichever `css` prop came first in the prop order. To ensure consumers do not either accidentally wipe our EUI's default styling, or are unable to pass in child `css` props, always check that you're manually merging in any `childProps.css` like so: ```tsx // This example will correctly merge child CSS export const EuiComponentName: FunctionComponent = ({ iconProps, ...rest }) => { const euiTheme = useEuiTheme(); const styles = euiComponentNameStyles(euiTheme); const cssStyles = [styles.euiComponentName]; // Include `childProps?.css` in the css array const cssIconStyles = [styles.euiComponentName__icon, iconProps?.css]; return (

) } ``` You can confirm that this behavior correctly merges Emotion CSS by using the `shouldRenderCustomStyles` test utility. Example usage: ```tsx import { shouldRenderCustomStyles } from '../../test/internal'; import { requiredProps } from '../../test/'; describe('EuiComponentName', () => { shouldRenderCustomStyles(, { childProps: ['iconProps'] }); it('renders', () => { // ... }) it('renders `iconProps`', () => { render() }); }); ``` ## Nested selectors For the most part, nested selectors should not be necessary. If a child element requires styling based on the parent's variant, pass the same variant type to the child element. ```ts export const euiComponentNameStyles = ({ euiTheme }: UseEuiTheme) => ({ euiComponentName: css``, // Sizes s: css``, m: css``, }); export const euiComponentNameChildStyles = ({ euiTheme }: UseEuiTheme) => ({ euiComponentName__child: css``, // Sizes s: css``, m: css``, }); ``` ```tsx export const EuiComponentName: FunctionComponent = ({...}) => { const euiTheme = useEuiTheme(); const styles = euiComponentNameStyles(euiTheme); const cssStyles = [styles.euiComponentName, styles[size]]; const childStyles = euiComponentNameChildStyles(euiTheme); const cssChildStyles = [childStyles.euiComponentName__child, childStyles[size]]; return (

) } ``` If for other reasons, it is absolutely necessary to target a child from within another selector, you should use the [class attribute selector](https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors) to match a part of the class string you expect to find. ```ts export const euiComponentNameStyles = ({ euiTheme }: UseEuiTheme) => ({ euiComponentName: css` [class*="euiComponentName__child"] {} `, }); ``` ## Creating `colorMode` specific components When creating components that rely on a specific `colorMode` from ``, use this pattern to create a wrapper that will pass the entire component `` details. - `_EuiComponentName` is an internal component that contains the desired functionality and styles. - `EuiComponentName` is the exportable component that wraps `_EuiComponentName` inside of ``. ```tsx const _EuiComponentName = ({ componentProps }) => { return

; } export const EuiComponentName = ({ componentProps }) => { const Component = _EuiComponentName; return ( ); } ); ``` **[Refer to EuiBottomBar to see an example of this pattern in practice and as an example of using `forwardRef`.](../../../packages/eui/src/components/bottom_bar/bottom_bar.tsx)** ## Emotion mixins & utilities When creating mixins & utilities for reuse within Emotion CSS, consider the following best practices: - Publicly-exported mixins & utilities should go in [`src/global_styling/mixins`](https://github.com/elastic/eui/tree/main/src/global_styling/mixins). Utilities that are internal to EUI only should live in [`src/global_styling/functions`](https://github.com/elastic/eui/tree/main/src/global_styling/functions). - If the mixin is simple and does not reference `euiTheme`, you do not need to create a hook version of it. - In general, prefer returning CSS strings in your mixin. - However, you should consider creating a 2nd util that returns a style object instead of a CSS string if the following scenarios apply to your mixin usage: - If you anticipate your mixin being used in the `style` prop instead of `css` (since React will want an object and camelCased CSS properties) - If you want your mixin to be partially composable, so if you think developers will want to obtain a single line/property from your mixin instead of the entire thing (e.g. `euiFontSize.lineHeight`) ## JS vs. CSS component variables In general, most component-specific style variables can remain JS-only (e.g., [euiStepVariables](https://github.com/elastic/eui/blob/068f0000532e6433383093d3488d7b1c4979c022/src/components/steps/step.styles.ts#L13-L19), [euiFormVariables](https://github.com/elastic/eui/blob/d39c0e988409f90f62af57174590044664b2bfce/src/components/form/form.styles.ts#L19)). These JS variable examples are generally used internally by EUI, and are not public top-level exports. There are some scenarios, however, where certain component style variables are important enough to be made globally available via a [CSS variable](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties). An example of this is **EuiHeader**: Fixed header height(s) and the page offset they cause need to be accounted for by multiple other EUI components (e.g. **EuiFlyout**, **EuiPageTemplate**), and potentially by custom consumer layouts. Using a global CSS variable allows **EuiHeader** to dynamically track the number of fixed headers and calculate total height in a single place. Other components can reuse that CSS variable without extra JS logic needed ([#7144](https://github.com/elastic/eui/pull/7144)). EUI components can set CSS variables in two places: globally, or at the nearest **EuiThemeProvider** wrapper level: ```tsx import React, { useEffect } from 'react'; import { useEuiTheme, useEuiThemeCSSVariables } from '../../services'; const EuiComponent = ({ ...props }) => { const { euiTheme } = useEuiTheme(); const { setGlobalCSSVariables, setNearestThemeCSSvariables, } = useEuiThemeCSSVariables(); useEffect(() => { // Sets the CSS variable at `:root` setGlobalCSSVariables({ '--euiSomeGlobalVariable': euiTheme.color.success }); // Sets the CSS variable on the nearest parent theme provider wrapper // If the nearest provider is EuiProvider, the variable is set globally on `:root` in any case setNearestThemeCSSVariables({ '--euiSomeThemeVariable': euiTheme.size.m }); }, []); return <>; } ``` While a global CSS variable makes sense for **EuiHeader**, for most components, nearest theme variables would likely make more sense. For example, **EuiForm** should respect any custom theme modifications and pass its modified form variables to any children, but not siblings or parent forms that do not have modifications. ```tsx // Normal form {/* ... Form controls that inherit global form variables */} // Form with a custom size scale {/* ... Form controls that inherit from the nearest theme variables */} ``` [See our EuiThemeProvider stories](http://localhost:6006/?path=/story/euithemeprovider--css-variables-nearest) to view an example of this behavior in the browser. ### Naming When naming your mixins & utilities, consider the following statements: - Always prefix publicly-exported functions with `eui` unless it's purely a generic helper utility with no specific EUI consideration - When creating both a returned string version and object version, append the function name with `CSS` for strings and `Style` for objects. Example: `euiMixinCSS()` vs `euiMixinStyle()`. ### API pattern For consistency, use the following pattern for style mixins that accept required and/or optional arguments: ```ts const euiMixin = ( euiTheme: UseEuiTheme; required: RequiredProperty; optional?: { optionalKey1?: OptionalProperty; optionalKey2?: OptionalProperty; } ) => {} ``` If the mixin does not accept required or optional properties, the argument can be removed. ## Writing unit tests for output styles If using complex utilities or calculations that leaves you unsure as to the output of your styles, it may be worth writing Jest snapshot tests to capture the final output. See [EuiText's style](https://github.com/elastic/eui/blob/main/packages/eui/src/components/text/text.styles.test.ts) [snapshots](https://github.com/elastic/eui/blob/main/packages/eui/src/components/text/__snapshots__/text.styles.test.ts.snap) or [EuiTitle](https://github.com/elastic/eui/blob/main/packages/eui/src/components/title/title.styles.test.ts) for an example of this. If writing straightforward or static CSS, unit tests should be unnecessary. ## FAQ ### Can the `css` prop be forwarded to a nested element? Emotion converts the `css` prop to a computed `className` value, merging it into any existing `className` prop on an element. We do not parse or handle these in any special way, so whichever element the `className` prop is applied to receives the styles created by Emotion. See https://codesandbox.io/s/emotion-css-and-classname-ohmqe7 for a playground demonstration. Sometimes apps want or need to provide styles (or other props) to multiple elements in a component, and in these cases we add a prop to the component that captures the extra information, spreading it onto the element. We can continue with this approach, allowing the `css` prop to be added for flexible styling. ### Which element in a custom component gets the `css` styling? Same as the above answer, whichever element is given the generated `className` is the styles' target. ### How should `createElement` usages be converted? Emotion provides its own `createElement` function; existing uses of `import {createElement} from 'react'` can be converted to `import {createElement} from '@emotion/react'` ### Why is stylelint / `yarn lint-css-in-js` giving me an `Unknown word (CssSyntaxError)` error? Unfortunately, a limitation of the CSS-in-JS syntax parser we're using is that `//` comments throw this error (see https://github.com/hudochenkov/postcss-styled-syntax#known-issues). You must convert all `//` comments to standard CSS `/* */` comments instead. ### Should I use Emotion's `css={theme => {}}` API? No. The [Emotion theme context](https://emotion.sh/docs/theming) that we include by default in `EuiThemeProvider` is intended for **consumer usage** and convenience, particularly with the goal of making adoption by Kibana devs easier. It is not intended for internal EUI usage, primarily because it can be too easily overridden by consumers who want to use their own custom Emotion theme vars and set their own ``. If this happens, and we're relying on Emotion's theme context, all of EUI's styles will break. When you're styling EUI components internally, you should use only EUI's theme context/`useEuiTheme()`, and not on Emotion's theme context (i.e., do not use the `css={theme => {}}` API). --- ### Contributing To Eui Documenting Changelogs (`wiki/contributing-to-eui/documenting/changelogs.md`) # Changelogs All upcoming changelogs should go into the `changelogs/upcoming/` directories. Our release script automatically handles collating these files on new EUI versions and appends a PR link. ## When to write a changelog - Any updates to the `packages/eui/src/` folder should include a changelog - `dependency` upgrades in `package.json` should contain a changelog ## When to skip a changelog Changes that do not impact consumers or end-users may use the `skip-changelog` label on PRs to bypass CI checks. Examples of these types of changes: - Documentation-only changes (e.g. changes to `wiki/` or `packages/website/`) - Infra/dev-only changes (e.g. changes to `.github/`, `.buildkite/` or `scripts/`) - Test-only changes (e.g. changes to `*.test.tsx`, `*.spec.tsx`, or `*.stories.tsx` files) - `dev-dependency` upgrades in `package.json` ## How to write a changelog * Create a new file with the ID/number of the pull request. * In `packages/eui`, you can use `yarn yo-changelog #####` (passing the PR ID/number) to automatically generate a changelog boilerplate file. * Reference [`packages/eui/changelogs/upcoming/_template.md`](/packages/eui/changelogs/upcoming/_template.md) for the canonical section ordering and formatting. * Create `**` wrapped subheadings for bug fixes, deprecations, or breaking changes. New features/enhancements should go at the top, and do not need a subheading. * Add a `-` list item for each significant change in the PR. Larger PRs may have multiple changes, whereas smaller PRs may have only one. * Write your entry in the **past tense**, starting with a verb (e.g. Added... , Fixed...). * Add a summary of what has changed, making sure it's informative to consumers who might be unaware of implementation details. * Avoid documenting internal implementation changes that don't affect the public interface. * Make sure the entry is as concise as can be. --- ### Contributing To Eui Documenting Writing Documentation (`wiki/contributing-to-eui/documenting/writing-documentation.md`) # Writing documentation - [Files and folders](#files-and-folders) - [Partials](#partials) - [Collapsible sidebar items](#collapsible-sidebar-items) - [Front matter](#front-matter) - [Documenting components](#documenting-components) - [Custom components available](#custom-components-available) - [Writing content](#writing-content) - [Headings](#headings) - [Links](#links) - [Admonitions](#admonitions) - [Code blocks](#code-blocks) - [Live demos](#live-demos) - [Full-screen example](#full-screen-example) - [Tables](#tables) - [Dos and Don'ts](#dos-and-donts) - [Figma asset](#figma-asset) - [Props table](#props-table) - [Images](#images) Code for the Elastic UI [documentation site](https://eui.elastic.co) can be found in the `packages/website` directory. The site is built with [Docusaurus](https://docusaurus.io/). ## Files and folders Documentation is written in Markdown. Files are stored in the `docs` folder and document files use [MDX](https://mdxjs.com/docs/what-is-mdx/), thus the `.mdx` file extension. This format allows writing React code alongside Markdown. It's also possible to import React code from `.tsx` files, which is useful for more complex examples. Check out the [MDX syntax documentation here](https://mdxjs.com/docs/what-is-mdx/#mdx-syntax). > [!TIP] > For formatting content always prefer using Markdown over React The folder structure matches the navigation and content structure, similar to common static site builders like Jekyll. For instance, for editing the Components / Containers / Accordion page, the content will be found in the `docs/components/containers/accordion.mdx` file. Files and folder names must use [kebab-case](https://developer.mozilla.org/en-US/docs/Glossary/Kebab_case), unlike the EUI convention to use snake_case. This makes it easier to keep URLs consistent without having to override Docusaurus defaults in the front matter. ### Custom components available There are a few React components that can be used in `.mdx` files without being imported. They are part of the [MDX scope](https://docusaurus.io/docs/next/markdown-features/react/#mdx-component-scope). Some of them, documented below, are: - [`Demo`](#demo-props) - [`FigmaAsset`](#figma-asset) - [`Guideline`](#guideline-props) - [`PropTable`](#props-table) ## Front matter The front matter is a section at the top of a Markdown file that contains metadata about the document. It's enclosed in triple dashes (`---`) and written in [YAML format](https://yaml.org/). A few important aspects of the document can be configured here: - `id` (unique to the document) - `slug` (to customize the URL) - `sidebar_label` - `sidebar_position` - `title` (if different from the h1) - `description` Check the Docusaurus docs for a [full list of fields](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-front-matter). ## Collapsible sidebar items To create a collapsible item in the sidebar, just add a folder in the file system containing one or more `.mdx` files. In Docusaurus these are called category items, and they can be configured by adding a `_category_.yml` file to the folder. By default the category label will be the folder name, this can be changed with the `label` field in the `_category_.yml` file. Other useful fields are `position` and `collapsed`. It's possible to make a collapsible item be a document as well, though this is not recommended. Set the `link` field to have `type: doc` and `id: `, with the `id` from the document it should point to. If the `id` is not explicitly set in the document file's [front matter](#front-matter), it's the relative path starting from the `docs` folder, without the file extension, e.g. `docs/components/containers/accordion`. Read more about [category metadata](https://docusaurus.io/docs/sidebar/autogenerated#category-item-metadata) and [file structure](https://docusaurus.io/docs/create-doc#organizing-folder-structure) in the Docusaurus docs. > [!WARNING] > Nesting items in the sidebar should be avoided when possible, deeply nested items can make the menu harder to use ## Documenting components All component pages should follow the following architecture: - Intro - Component: a bare-bones example of the component in its default form - Usage (_optional_): examples of different states and use-cases - Guidelines (_optional_): e.g. dos and don'ts - Props ## Partials A document can be split into different files when content is too long, for easier editing. Markdown files prefixed with an underscore will be ignored when generating the sidebar navigation. These hidden files can be imported and rendered in the main document. For example, the document for the Modal page is `containers/modal/index.mdx`: containers/ modal/ _guidelines.mdx _usage.mdx index.mdx Usage and Guidelines sections have their own file that can be imported: import Usage from './_usage.mdx'; ## Usage ## Guidelines import Guidelines from './_guidelines.mdx'; Read more about [importing Markdown files](https://docusaurus.io/docs/markdown-features/react#importing-markdown) in the Docusaurus docs. ## Writing content As previously mentioned, using Markdown is highly encouraged. It makes it easier for anybody to contribute to the documentation. During the build step of the website, elements with a counterpart in EUI will be accordingly replaced, e.g. a link with `EuiLink`, a inline code block with `EuiCode`, etc. ### Headings Headings in Markdown are created with a hash symbol in a new line. The number of hashes will determine the heading level, `#` for 1, `##` for 2, etc. > [!IMPORTANT] > Do not use heading levels for styling, use them to properly structure the document hierarchically ### Links Markdown is the recommended syntax for creating links. Docusaurus will take care of rendering it correctly. ```md [This is a link](https://example.com) ``` To link between documents, use **relative file paths, including the file extension**, e.g. `[EuiPanel](../containers/panel/index.mdx)` Read more about [Markdown links](https://docusaurus.io/docs/markdown-features/links) in the Docusaurus docs. ### Admonitions The syntax for creating admonitions is wrapping a paragraph in three colons, e.g. `:::`. The type of admonition and title can be defined after the first three colons. This will render `EuiCallOut`. ```mdx :::info This is the title Here's some content ::: ``` There are 6 types of admonitions supported, with icon and color respectively. - `note` - `tip` - `info` - `accessibility` - `warning` - `danger` ### Code blocks A code block or code snippet can be created by wrapping text in backticks, e.g. \`code\`. For a simple one-liner, single backticks are enough. To create a multiline snippet or code block, use three backticks. For syntax highlighting, the language name can be added right after the first three backticks. ```html Hello World ``` Code blocks can be used to generate live demos, where a React component that is exported in the snippet will be rendered on the page. To do that, append the word "interactive" after the language name, usually `tsx`. ```tsx interactive export default () => (

Hello World

) ``` More advanced usage with the [`Demo` component](#live-demos) can be found right below. ### Live demos When plain code blocks are not enough, the `Demo` component can be used. It's available without being imported so it can be used straightaway. > [!NOTE] > They're called "live" demos because the source code can be edited right there on the page and the preview will update The benefits of the `Demo` component over plain code blocks are mainly: - that the scope of the demo can be extended with imports from the document, and - it's possible to add a wrapper component for the preview and adjust the padding. #### `Demo` props - `children` - A `tsx` code block - `scope` - An object to extend the scope of the demo with additional properties - `isSourceOpen` - Whether the source code editor is open by default (`false`) - `previewPadding` - Adjust the padding of the preview - `previewWrapper` - A wrapper component for the preview Check the [source code here](https://github.com/elastic/eui/tree/main/packages/docusaurus-theme/src/components/demo). #### Usage example > [!TIP] > Remember to wrap imports in ```mdx-code-block` ```mdx-code-block import previewWrapper from './preview_wrapper.tsx'; ``` ```tsx import React, { useState } from 'react'; import { EuiButton } from '@elastic/eui'; export default () => { const [counter, setCounter] = useState(0); const updateCounter = () => setCounter(x => x + 1); return ( Clicked {counter} times ) } ``` #### CodeSandbox The `` component includes built-in **CodeSandbox integration**. It displays a button that, when clicked, opens a new CodeSandbox instance containing your snippet. To ensure CodeSandbox functions properly, verify that all references are resolvable: - all necessary React and EUI components are imported directly, - all relative imports in the snippet are direct siblings (e.g. `import { Component } from './component';`), - all local files used (such as components or SVGs) are passed to the `extraFiles` prop as stringified content: ````mdx ```mdx-code-block import icon from './icon.svg'; import iconSource from '!raw-loader!./icon.svg'; ``` ```tsx import { EuiImage } from '@elastic/eui'; import icon from './icon.svg'; export default () => { return ( ) } ``` ```` `scope` and `extraFiles` serve different purposes. `scope` is used to inject variables into the snippet execution context while `extraFiles` is used to pass additional files to the CodeSandbox instance. ### Full-screen example The convention for creating full-screen examples, where the entire browser screen is needed to demo a certain component combination or pattern, is to create a Storybook story and link to it from the docs. There's a `StorybookLink` component that makes this easy and consistent, by handling the URL appropriately depending on the environment. It's expected for the link to be preceded by a heading and a short description. The story's `id` can be found in the URL. It's the part after `/index.html?path=/story/`. ## A heading for the example Here it's explained what the examples represents. ```mdx-code-block import { StorybookLink } from '@site/src/components'; ``` ### Tables There are two supported ways to create tables in MDX - using Markdown tables syntax or using the EUI table components like [`EuiTable`](https://eui.elastic.co/docs/components/tables/custom) or [`EuiBasicTable`](https://eui.elastic.co/docs/components/tables/basic): * **Markdown tables** syntax should only be used for simple, text-only tables. The Markdown representation of a table must be easily readable. * **[EuiTable](https://eui.elastic.co/docs/components/tables/custom)** components should be used for longer and more complex tables * **[EuiBasicTable](https://eui.elastic.co/docs/components/tables/basic)** should be used for multi-column tables, when the data comes from JS objects or isn't easily readable when directly defined using MDX syntax. Just like with [partials](#partials), the code for the table can be separated in its own file and imported into the MDX document where it'll be displayed. For example: components/ my-component/ nice_table.tsx index.mdx `nice_table.tsx` can export a component that renders [EuiBasicTable](https://eui.elastic.co/docs/components/tables/basic-tables): ```tsx import { css } from '@emotion/react'; import { EuiBasicTable, EuiBasicTableColumn, // ... } from '@elastic/eui'; export const NiceTable = () => { const items = [ // ... ]; const columns = [ // ... ]; return ; } ``` And then in `index.mdx` the table can be rendered: ## A heading for the table ```mdx-code-block import { NiceTable } from './nice_table'; ``` ### Dos and Don'ts For dos and don'ts sections there's a `Guideline` component with the appropriate styles built-in. To display one next to the other, a [EuiFlexGroup](https://eui.elastic.co/docs/components/layout/flex/flex-group) can be used: ```tsx

Yep content

Nope content

``` #### `Guideline` props - `children` - The content inside, can be other components - `type` - `do`, `dont` or `default` - `text` - The actual guideline text - `panelPadding` (optional) - To adjust the padding of the panel - `panelStyle` (optional) - To further customize the panel styles ### Figma asset Use `FigmaAsset` to show a Figma design in docs. By default it renders a static image (SVG preferred). Pass `type="embed"` to show an interactive Figma iframe instead. Props are a discriminated union on `type`: image mode requires `src` (and forbids embedding-only combinations); embed mode forbids `src`. `title` is always required for accessibility. **Image (default)** — import a colocated asset as a URL (use `!url-loader!` for SVGs; bare `.svg` imports become React components via SVGR). WebP/PNG imports work the same way if you need them later: ```mdx import confirmationModal from '!url-loader!./assets/modal_confirming-an-action.svg'; ``` **Embed** — interactive iframe from the Figma `url`: > **Important note:** Use it only when necessary — only when users need to zoom into UI details. It impacts rendering performance and stability in the sections where applied. ```mdx ``` | Prop | Description | | ---- | ----------- | | `url` | Figma file/node URL (used for embed; kept as source reference for images) | | `src` | Image URL string — SVG preferred; WebP/PNG supported (**required** for `type="image"`; not allowed for `type="embed"`) | | `type` | `"image"` (default) or `"embed"` | | `title` | **Required** accessible text (image `alt` / iframe `title`) | ### Props table The Props table should always go last in a document. There is a `PropTable` component available without being imported that will take the props information from the `@elastic/eui-docgen` package in the `definition` prop. If more than one table is needed because the component has many exports, place one table after the other. It should look like this: ## Props ```mdx-code-block import docgen from '@elastic/eui-docgen/dist/components/page'; ``` To customize the table `PropTable` also takes a `headingLevel` prop (h1–h6) and a `showTitle` boolean. ### Images Typically, just use markdown: ```mdx ``` If you need to add CSS to do something like constraining the width, use an `img` tag: ```mdx import error404 from './images/error-page-404.webp'; An empty prompt component which reads, 404, we can't find the page you're looking for. If you typed the URL, check it's correct. If you clicked a link, contact your administrator: admin@example.co.

An empty prompt component which reads, 404, we can't find the page you're looking for. If you typed the URL, check it's correct. If you clicked a link, contact your administrator: admin@example.co.

``` --- ### Contributing To Eui Testing Automated Accessibility Testing (`wiki/contributing-to-eui/testing/automated-accessibility-testing.md`) # Accessibility testing The goal is for all EUI components to be run through [axe](https://www.deque.com/axe/). Please refer to [issue #6300](https://github.com/elastic/eui/issues/6300) to see components under test. ## What is axe? axe is an "[accessibility engine for automated Web UI testing](https://github.com/dequelabs/axe-core)". Automated tests cover ~30% of accessibility requirements but ~60% of accessibility bugs are caught by automated tests. Automated testing can't replace manual testing, but it's an important baseline for all of our components. ## How to run the Cypress accessibility tests? * `test-cypress-a11y` runs the accessibility test suite in a local headless Cypress environment. * `test-cypress-dev` runs the test suite using your dev server (assumed to be `http://localhost:8030`) and the Cypress test runner. ### How to run accessibility tests against 1 component? Though it's not setup to be run this way, there are two ways to do it. The recommended route is to install the axe addon (for [Chrome](https://chrome.google.com/webstore/detail/axe-web-accessibility-tes/lhdoppojpmngadmnindnejefpokejbdd), [Firefox](https://addons.mozilla.org/en-US/firefox/addon/axe-devtools/), or [Edge](https://support.microsoft.com/en-us/microsoft-edge/download-the-new-microsoft-edge-based-on-chromium-0f4a3dd7-55df-60f5-739f-00010dba52cf)). Navigate to any page and run the analyzer from your browser's developer tools. This will return the same* results to you while also giving you some convenience utilities like highlighting the exact element that's failing. \* It might not actually be the same in a couple cases (e.g., we've disabled some rules or a recent update that was pushed to the addon but we haven't updated yet) but it will generally be more strict than we are, so you should never see something in CI that you can't see in the addon. ## Deconstructing an error message We have updated how accessibility violations appear in your terminal or CI logs. Each URL with violations will write a table like the one shown here. | index | id | impact | description | nodes | | :---: | :---: | :---: | :---: | :---: | | 0 | 'aria-valid-attr-value' | 'critical' | 'ARIA attributes must conform to valid values' | 1 | | 1 | 'nested-interactive' | 'serious' | 'Nested interactive elements are not announced by screen readers' | 3 | All error messages follow this same structure: * The `index` is a 0-based count of accessibility violations on a page. * The `id` maps to an [axe-core rule description](https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md) on GitHub. These rules link to more information on the Deque University site. * The `impact` describes how much a violation will prevent or degrade the user experience. * The `description` will give a one sentence explanation of the problem. * The `nodes` will tell you how many violations of this type are on the page. The test runner will give you a total count of issues at the end of the run. Any violations should be confirmed using the [axe browser plugin](https://deque.com/axe) in the [EUI design system site](https://eui.elastic.co), or running a server locally. The axe browser plugin is available for Chrome, Firefox, and Edge. ## Testing environment Run the suite locally with `yarn test-cypress-a11y`. CI already runs it on every pull request (Buildkite job **Cypress accessibility (a11y) tests on React 18**). --- ### Contributing To Eui Testing Cypress Testing (`wiki/contributing-to-eui/testing/cypress-testing.md`) # Cypress testing Currently, EUI only uses [Cypress component testing](https://docs.cypress.io/guides/component-testing/introduction) as opposed to its full E2E test runner. This is ideal for isolating/focusing on specific components while reducing traditional E2E start times. ## Running tests `yarn test-cypress` runs component tests headlessly (no window appears) `yarn test-cypress-a11y` runs component accessibility tests headlessly (no window appears) `yarn test-cypress-dev` launches a chrome window controlled by Cypress, which lists out the discovered tests and allows executing/interacting from that window. ### Setting the theme By default tests are run using the light theme. Dark mode can be enabled by passing the `--theme=dark` option. ### Testing specific version of React By default, EUI Cypress tests are run using the latest supported version of React (18). You can change that behavior by passing `--react-version` set to `17` or `18` (peer range). ### Cypress arguments You can also pass [Cypress CLI arguments](https://docs.cypress.io/guides/guides/command-line). For example: ```bash # Only run a single specific test file, e.g. onBoarding.js yarn test-cypress --spec '**/{file}.spec.tsx' # Opt to run Chrome headlessly yarn test-cypress --headless # Overriding config settings, e.g. enabling video recording yarn test-cypress-dev --config video=true # Overriding env variables yarn test-cypress-dev --env password=foobar ``` ## Writing tests ### When to write Cypress tests Cypress tests should primarily be written for functionality that Jest/JSDom can't realistically replicate, for example: - Focus state - Portals - 3rd party dependencies - Native DOM behaviors (e.g., scrolling, label<>input clicks) ### How to write Cypress tests Cypress has its own specific [`cy.` API/commands](https://docs.cypress.io/api/commands/get#Arguments), of which you will likely be using `cy.get()`, `cy.find()`, and either `cy.click()` or `cy.type()` to interact with DOM elements. Here's a small example test: ```jsx import { mount } from '@cypress/react'; import TestComponent from './test_component'; describe('TestComponent', () => { it('takes user input, submits it, and displays the resulting output', () => { mount(); cy.get('[data-test-subj="someInput"]').type('hello world'); cy.get('[data-test-subj="submitButton"]').click(); cy.get('[data-test-subj="someOutput"]').contains('HELLO WORLD'); }); }); ``` #### Naming your test files Create Cypress test files with the following name patterns to run in specific situations: * `{component name}.spec.tsx` will run a full component test as part of every build * `{component name}.a11y.tsx` will run an accessibility test using [Cypress Axe](#cypress-axe) These test files should be in the same directory as `{component_name}.tsx`. #### Do's and don'ts * DO read through Cypress's [best practices](https://docs.cypress.io/guides/references/best-practices) recommendations * DO use the `data-test-subj` attribute to mark parts of a component you want to `find` later. * DON'T depend upon class names or other implementation details for `find`ing nodes, if possible. * DON'T extend the `cy.` global namespace - instead prefer to import helper functions directly ### Recording failed Cypress tests on CI EUI now has the ability to record failed Cypress tests as Buildkite CI artifacts. This feature is turned off by default, but can be turned on by changing `video: false` to `video: true` in [`packages/eui/cypress.config.ts`](https://github.com/elastic/eui/blob/main/packages/eui/cypress.config.ts). You can verify videos are being recorded by changing a Cypress test to fail on purpose, then running `yarn test-cypress` locally. Video files will be stored in `packages/eui/cypress/videos/`. The EUI team has configured Cypress to only keep videos for failing tests. Videos are automatically compressed to make the artifact upload smaller. ### Cypress Axe EUI components are tested for accessibility on every pull request (Buildkite Cypress a11y job) and locally via `yarn test-cypress-a11y`. This allows us to test changes to the DOM such as accordions being opened, or modal dialogs being triggered, more comprehensively. We use [cypress-axe](https://github.com/component-driven/cypress-axe) to access the underlying axe-core API methods and rulesets. #### How to write cypress-axe tests ```jsx // Names must follow the `{component name}.a11y.tsx` pattern to be run correctly // accordion.a11y.tsx describe('Automated accessibility check', () => { it('has zero violations when expanded', () => { cy.mount( Any content inside of EuiAccordion will appear here. We will include a link to confirm focus. ); cy.get('button.euiAccordion__button').click(); cy.checkAxe(); }); }); ``` #### Configuring `cy.checkAxe()` The `cy.checkAxe()` helper method has four optional parameters: - `skipFailures` - Set to `true` to enable report-only mode. Report-only will run the entire suite without causing tests to return early. - `context` - This could be the document or a selector such as a class name, id, or element. The `context` default is `div#__cy_root`. - `axeConfig` - The [axe.run API](https://www.deque.com/axe/core-documentation/api-documentation/#api-name-axerun) can be modified to include or exclude elements, individual rules, or entire rulesets. - `callback` - Define a [custom violations callbac](https://github.com/component-driven/cypress-axe#violationcallback-optional) if you need to add side effects or change the reporting structure ```jsx // Create a custom ruleset by extending EUI defaults import { defaultAxeConfig } from '../../cypress/support/a11y/axeCheck'; const customAxeConfig = { ...defaultAxeConfig, runOnly: { type: 'tag', // Add best-practices to existing rulesets values: [...defaultAxeConfig.runOnly.values, 'best-practices'], }, }; // Violations will use the custome ruleset and cause tests to fail cy.checkAxe(false, customAxeConfig); ``` ### Cypress Real Events > Cypress default events are simulated. That means that all events like `cy.click` or `cy.type` are fired from JavaScript. That's why these events will be untrusted (`event.isTrusted` will be `false`) and they can behave a little different from real native events. But for some cases, it can be impossible to use simulated events, for example, to fill a native alert or copy to the clipboard. This plugin solves this problem. [Cypress Real Events](https://github.com/dmtrKovalenko/cypress-real-events#why) #### Why Cypress Real Events? Cypress Real Events uses the [Chrome Devtools Protocol](https://chromedevtools.github.io/devtools-protocol/) to handle behaviors like a real browser. This gives us a better way to test complex events like mouse hover and keyboard focus. By using real events and making assertions against them, we can test keyboard and screen reader accessibility as users change the local state. #### How to write Cypress (real event) tests The [Cypress Real Events API](https://github.com/dmtrKovalenko/cypress-real-events#api) works seamlessly with existing `cy()` methods. If you want to press a button using Cypress Real Events, you could use `realPress('Tab')` as a replacement for the `cy.tab()` synthetic method. If you want to press multiple keys (also known as a **chord**), you should pass an array like `['Shift', 'Tab']` to your helper method. All Cypress Real Events methods are prefixed with the string "real". Here's a small example test: ```jsx import TestComponent from './test_component'; describe('TestComponent', () => { it('presses a button using the Enter key', () => { /* Use the `realMount()` command to set focus in the test window */ cy.realMount(); /* Activate a button with a real keypress event */ cy.get('[data-test-subj="submitButton"]').realPress('Enter'); /* Assert the button has focus and the aria-expanded attribute has updated */ cy.focused().invoke('attr', 'aria-expanded').should('equal', 'true'); }); it('presses a button using the Space key', () => { /* Assert the button also accepts the Spacebar keypress */ cy.realMount(); cy.get('[data-test-subj="submitButton"]').realPress('Space'); cy.focused().invoke('attr', 'aria-expanded').should('equal', 'true'); }); }); ``` #### Do's and don'ts for Cypress Real Events * DO follow [all previous guidance](#dos-and-donts) for writing Cypress tests * DO use the correct mounting method: * Use `cy.realMount()` if your component doesn't receive focus automatically **OR** * Use `cy.mount()` for components that receive focus on render * DO be on the lookout for new features! ## Debugging tests For debugging failures locally, use `yarn test-cypress-dev`, which allows you to run a single specific test suite and runs tests in a browser window, making dev tools available to you so you can pause and inspect DOM as needed. > :warning: As a general rule, we generally recommend taking a break and not clicking around while tests are running. This can eliminate or lower the possibility of hard-to-reproduce/intermittently flaky behavior and timeouts due to user interference. ### Artifacts All failed tests will output a screenshot to a `screenshots/` folder (`cypress/screenshots`). We strongly recommend starting there for debugging failed tests to inspect error messages and UI state at point of failure. To track what Cypress is doing while running tests, you can pass in `--config video=true` which will output screencaptures to the `cypress/videos/` folder for all tests (both successful and failing). This can potentially provide more context leading up to the failure point, if a static screenshot isn't providing enough information. > ℹ️ We have videos turned off in our config to reduce test runtime, especially on CI, but suggest re-enabling it for any deep debugging. ### CI debugging Failing screenshot artifacts (as well as Cypress logs) are generated by our Jenkins CI. TODO: Instructions on where to click to see the relevant artifact(s)/screenshots --- ### Contributing To Eui Testing Eui Test Helpers (`wiki/contributing-to-eui/testing/eui-test-helpers.md`) # EUI test helpers [`@elastic/eui-test-helpers`](../../../packages/test-helpers) ships Playwright Component Objects used by downstream end-to-end tests (Kibana Scout). Each helper has validation tests that run its public API against the real component in Storybook. This page covers how those tests run in CI; for the package itself (directory layout, adding a Component Object) see the package [CONTRIBUTING](../../../packages/test-helpers/CONTRIBUTING.md). ## Running locally Start Storybook, then run the suite (it attaches to the running dev server): ```shell yarn workspace @elastic/eui build:workspaces # one-time yarn workspace @elastic/eui start # Storybook on http://localhost:6006 # in another terminal: yarn workspace @elastic/eui-test-helpers exec playwright install chromium # one-time yarn workspace @elastic/eui-test-helpers test ``` See the package [CONTRIBUTING](../../../packages/test-helpers/CONTRIBUTING.md) for the full local workflow and the HTML report. ## On every pull request `eui-pull-request-test` runs two helper steps (`test-helpers` task in [`pipeline_test.sh`](../../../.buildkite/scripts/pipelines/pipeline_test.sh)): - **Validation** — builds the EUI workspaces and Storybook, then runs the full Playwright suite once. Storybook is served by Playwright's `webServer` from the static build. - **Flake detection** — [`pipeline_test_helpers_flaky.sh`](../../../.buildkite/scripts/pipelines/pipeline_test_helpers_flaky.sh) diffs the PR against its merge base and, for any changed component with a correlated helper, runs that helper's specs `--repeat-each=25` to surface flakiness — even when the helper itself was not touched. A flaky failure fails the build. It is a no-op when no correlated component changed. ### Component ↔ helper correlation The correlation is by directory path, so keeping the helper's directory in parity with the EUI component's is all that is required. See [Flake detection in the package CONTRIBUTING guide](../../../packages/test-helpers/CONTRIBUTING.md#ci-integration) for the exact rule. --- ### Contributing To Eui Testing Screen Reader Testing Matrix (`wiki/contributing-to-eui/testing/screen-reader-testing-matrix.md`) # Screen reader testing matrix This document was created based on analytics compiled in July 2022. The analytics reflect the most common browsers, screen resolutions, and operating systems among Elastic Cloud users. The data was compiled anonymously and will only be used to inform testing priorities. ## Testing tiers * **Tier 1 (T1):** Should be tested for all new components or significant experience updates * **Tier 2 (T2):** Test as time allows during a regular PR review cycle * **Tier 3 (T3):** Test as requested by customers or teammates ## Testing matrix | | JAWS
(Win) | NVDA
(Win) | VoiceOver
(MacOS) | Orca
(Linux) | iOS VoiceOver
(Apple devices) | TalkBack
(Android devices) | | --- | :---: | :---: | :---: | :---: | :---: | :---: | | Chrome | T1 | T1 | ❌ | T3 | ❌ | T3 | | Firefox | T2 | T1 | T2 | T3 | ❌ | ❌ | | Edge | T2 | T2 | ❌ | ❌ | ❌ | ❌ | | Safari | ❌ | ❌ | T1 | ❌ | T3 | ❌ | ## Resources ### Desktop screen readers * [Using JAWS to Evaluate Web Accessibility](https://webaim.org/articles/jaws/) * [Keyboard shortcuts for JAWS](https://webaim.org/resources/shortcuts/jaws) * [Using NVDA to Evaluate Web Accessibility](https://webaim.org/articles/nvda/) * [Keyboard Shortcuts for NVDA](https://webaim.org/resources/shortcuts/nvda) * [Using VoiceOver to Evaluate Web Accessibility](https://webaim.org/articles/voiceover/) ### Mobile device screen readers * [VoiceOver on Mobile](https://webaim.org/articles/voiceover/mobile) * [Using TalkBack to Evaluate Web Accessibility](https://webaim.org/articles/talkback/) --- ### Contributing To Eui Testing Testing In Kibana (`wiki/contributing-to-eui/testing/testing-in-kibana.md`) # Testing EUI features in Kibana ahead of time > [!TIP] > **Which page?** > - **This page** - run EUI in local Kibana or stage a `.tgz` Kibana draft PR. > - **[Nightly and Regression](https://github.com/elastic/eui-private/wiki/Nightly-and-Regression-testing-pipeline)** (internal) - Kibana CI against an npm snapshot. > - **[Upgrading EUI in Kibana](https://github.com/elastic/eui-private/wiki/Upgrading-EUI-in-Kibana)** (internal) - ship an official EUI release into Kibana. Most PRs should be tested in Kibana before merging into EUI main. Test a built version of EUI against Kibana and consider [staging the integration](#staging-integrations) to ensure the upgrade process is as painless as possible. ## Staging Integrations Use this **Staging Workflow** to assist the EUI maintainers in integrating your PR into Kibana during an upgrade. Useful when: - PR involves breaking changes - You want to apply a new feature in Kibana to ensure adoption - Existing styles may need to be tweaked - There are test failures, especially integration tests 1. **Stage in Kibana:** Create a **Draft PR** in the Kibana repo. Use this to handle test failures, style tweaks, or API migrations. 2. **Reference in EUI PR:** Link the Kibana Draft in your EUI PR description. 3. **Prep commits:** Add each staged commit URL under `# @next` in [`packages/release-cli/kibana-prep-commits`](https://github.com/elastic/eui/blob/main/packages/release-cli/kibana-prep-commits) (one URL per line). Nightly and the upgrade PR cherry-pick that list. 4. **Final Upgrade:** The upgrader will cherry-pick your staged commits into the final Kibana version bump PR. ### Example: Staging Workflow | Step | Link | Action | | :--- | :--- | :--- | | **1. Staging** | [Kibana Draft \#248805](https://github.com/elastic/kibana/pull/248805) | Create commits for API updates, style adjustments, and test fixes. | | **2. Source** | [EUI PR \#9308](https://github.com/elastic/eui/pull/9308) | Note: *"All commits in the linked PR should be included in the upgrade."* | | **3. Prep list** | [`kibana-prep-commits`](https://github.com/elastic/eui/blob/main/packages/release-cli/kibana-prep-commits) | Add each staged commit URL under `# @next`. | | **4. Final** | [Kibana Upgrade \#253286](https://github.com/elastic/kibana/pull/253286) | Upgrader cherry-picks staged commits into the version bump. | ### Recommended Commit Structure Keep staged commits atomic to simplify cherry-picking for the upgrader: * `refactor: update [some Kibana code] to use new EUI API` * `style: adjust styles for [some EUI change]` * `test: update snapshots for [some EUI change]` * `test: fix broken integration tests for [some EUI change]` ## Testing local EUI in local Kibana `yarn link` doesn't work between EUI and Kibana - EUI is on Yarn v4 and Kibana is on pnpm, and their package managers are not interoperable. Instead, you have two options depending on your goal: - For **local development** against a Kibana instance running on your machine, use the [`yarn watch --kibana`](../developing/developing-in-kibana.md) watcher. - For **CI validation** — opening a Kibana draft PR so Kibana's CI runs against your EUI changes — use `yarn build-pack` (described below) to produce a `.tgz` that you commit to the Kibana PR. ### In EUI: EUI is a monorepo and to build and test `eui` locally in Kibana you'll need to ensure that the internal dependency packages are correctly linked as well. First, update the `package.json` in `eui/packages/eui` as follows: - remove `@elastic/eui-theme-common` from dependencies - add `"@elastic/eui-theme-common": "workspace:^"` to devDependencies - add `"@elastic/eui-theme-common": "{CURRENT_VERSION}"` to peerDependencies, e.g. `"@elastic/eui-theme-common": "1.0.0"` Then run the following command: ```bash # eui/packages/eui yarn build-pack ``` If you made changes to `eui-theme-common` and/or `eui-theme-borealis` directories you'll need to build those packages as well: ```bash # eui/packages/eui-theme-common yarn build-pack ``` ```bash # eui/packages/eui-theme-borealis yarn build-pack ``` This will create the required `.tgz` file(s) with the changes in your `eui` (and `eui-theme-common`/ `eui-theme-borealis`) directory. At this point you can move it anywhere. > [!IMPORTANT] > If the `.tgz` is going to be committed to Kibana, rename it to snake_case (e.g. `elastic_eui_xx.x.x.tgz`). Kibana's `file_casing` quick check fails the PR on hyphenated names like the `elastic-eui-xx.x.x.tgz` that `yarn pack` produces. ### In Kibana: Point the `package.json` file in Kibana to that file: `"@elastic/eui": "/path/to/elastic_eui_xx.x.x.tgz"`. Then run the following commands at Kibana's root folder: ```bash pnpm kbn bootstrap --no-validate && pnpm start ``` * The `--no-validate` flag is required when bootstrapping with a `.tgz`. * Change the name of the `.tgz` after subsequent `yarn build-pack` steps (e.g., `elastic_eui_xx.x.x_1.tgz`, `elastic_eui_xx.x.x_2.tgz`). This is required for the package manager to recognize new changes to the package. * Running Kibana with `pnpm start` ensures it starts in dev mode and doesn't use a previously cached version of EUI. ### Deploying local EUI in Kibana Elastic engineers have the option to deploy a local EUI package in Kibana. To do so, do the following: #### Generate and link a local EUI package - Follow the steps above to create a local package of EUI using `yarn build-pack` - Copy the generated `.tgz` package file(s) to the Kibana root and rename them to snake_case (see the note above) - Point the `package.json` file in Kibana to that local file: `"@elastic/eui": "file:./elastic_eui_xx.x.x.tgz"`. - Add `"@elastic/eui-theme-common"` to the `package.json` and point it either to the local package you copied, or add the published version that matches the version listed as a dependency in your local `@elastic/eui` package ```bash # default release version, no local package for @elastic/eui-theme-common "@elastic/eui-theme-common": "3.0.0" # with local package added "@elastic/eui-theme-common": "file:./elastic_eui_theme_common_xx.x.x.tgz" ``` - Run `pnpm kbn bootstrap` (requires pnpm on PATH — see [Developing EUI locally in Kibana](../developing/developing-in-kibana.md)) - Commit the changed files (`package.json`, `pnpm-lock.yaml` and EUI `.tgz` package) and push your branch - Create a Kibana (draft) pull request - Kibana CI will run tests on this instance with your custom EUI package - To ensure CI works correctly, you'll need to add `@elastic/eui-theme-common` to `packages/kbn-dependency-ownership/src/rule.ts` ([example](https://github.com/elastic/kibana/pull/227054/files)) and `src/dev/license_checker/config.ts` ([example](https://github.com/elastic/kibana/pull/227054/files#diff-373e937e773b0370ab1d28f3cf90251dcbd3cf95546f8c54b6bb6b1f999999dcR96)) #### Deploy the custom EUI package After you have created a Kibana PR following the steps above, there are two ways you can deploy your local EUI package in Kibana. ##### Using labels - Add the labels `ci:cloud-deploy` and `ci:cloud-persist-deployment` on your PR and ensure the CI pipelines run by checking the "Click to trigger kibana-deploy-cloud-from-pr for this PR!" checkbox in the comment from **elasticmachine** - Once the pipelines are finished, **kibanamachine** will post a message with a link to the credentials on Buildkite, there you'll find a link to the deployment e.g. https://kibana-pr-228477.kb.us-west2.gcp.elastic-cloud.com and a command to get the credentials - Run the `vault` command to get the credentials in your terminal (if you never used the `vault` CLI, continue reading) - To use HashiCorp's `vault` CLI - [Install it](https://developer.hashicorp.com/vault/install), if you're on a Mac you can use [homebrew](https://brew.sh/) - Login for the [Infra Vault (production)]((https://docs.elastic.dev/vault/accessing)) by running: - `export VAULT_ADDR=https://secrets.elastic.co:8200` - `vault login -method=oidc` ##### Using Kibana a la carte Follow the instructions in [Kibana a la carte](https://kibana-a-la-carte.kbndev.co/) to deploy your PR. --- ### Contributing To Eui Testing Unit Testing (`wiki/contributing-to-eui/testing/unit-testing.md`) # Unit testing EUI unit tests run on Jest. New tests should be written with [React Testing Library (RTL)](https://testing-library.com/docs/react-testing-library/intro/). A subset of legacy tests still uses [Enzyme](https://enzymejs.github.io/enzyme/) and is being migrated — see [Legacy: Enzyme](#legacy-enzyme) below. ## Running tests `yarn test-unit` runs **all** Jest unit tests at once. `yarn test-unit button` will run tests with "button" in the spec name. You can pass other [Jest CLI arguments](https://jestjs.io/docs/cli). For example: `yarn test-unit -u` will update your snapshots. Note: if you are experiencing failed CI builds (Buildkite) related to snapshots, then try clearing the cache first `yarn test-unit --clearCache`. `yarn test-unit --watch` watches for changes and runs the tests as you code. `yarn test-unit --coverage` generates a code coverage report showing you how fully-tested the code is, located at `reports/jest-coverage`. ## Naming your test files Create test files with the name pattern of `{component name}.test.tsx` in the same directory which contains `{component name}.tsx`. ## Targeting files to test You can also add any string to the end of the command to run the tests only on test files whose path contains that string. For example, `yarn test-unit button` will match both `accordion/button.test.tsx` (filename match) and `button/icon.test.tsx` (parent directory match), but not `card.test.tsx`. `yarn test-unit --testMatch=react / --testMatch=non-react` will test specifically only `.tsx` files vs. non-`.tsx` files. If not specified, both types of tests will run automatically. `yarn test-unit --react-version=18` will run tests against a specific React version that EUI supports (currently 17-18). ## Test helpers The [`packages/eui/src/test`](/packages/eui/src/test) module exports functions and constants to help you write better tests. **Use these for new tests:** * `requiredProps` is a list of all props almost all components should support. * `shouldRenderCustomStyles` automatically asserts that consumer classNames, Emotion CSS, and custom styles are merged correctly with EUI's styles. * The exports within `test/rtl` (`render`, `screen`, and `within`) provide out-of-the-box `data-test-subj` querying. `render` provides automatic `EuiProvider` wrapping. * _Note:_ Unlike RTL's recommendation to [use `screen` for queries](https://testing-library.com/docs/queries/about/#using-queries), EUI prefers, for consistency, to destructure test queries from the `render()` API. ### Test helper naming pattern If the test helper includes `enzyme` or other libraries included only in `devDependencies`, use the `*.test_helper.[ts, tsx]` naming pattern to exclude the component from production builds, or place the helper in a namespaced folder. ## Legacy: Enzyme EUI is migrating away from Enzyme. **Do not write new Enzyme tests** — use RTL (see [Test helpers](#test-helpers) above). The helpers below exist only to support existing Enzyme tests until the migration completes: * `findTestSubject` helps you find DOM nodes in mounted components. * `takeMountedSnapshot` generates a snapshot of a mounted component. When touching a legacy Enzyme test, prefer porting it to RTL if the change is non-trivial. ## Test design ### Do's and don'ts * DO use the `data-test-subj` attribute to mark parts of a component you want to `find` later. * DON'T depend upon class names or other implementation details for `find`ing nodes, if possible. * DON'T use snapshots, except for an initial `it renders` test. Prefer using specific assertions instead. ### Anatomy of a test A good test will document: * The default state of the component. * The inputs for each prop, and the associated outputs. * Errors. * Special behavior, e.g. keyboard navigation, async behavior, DOM manipulation under the hood. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## Writing mock component files A component file can be mocked for snapshot simplification or to mitigate nondeterministic rendering in test environments. See [`src/components/icon`](/packages/eui/src/components/icon/) for a example. _Mock component files are currently only used as part of consuming project test environments. To use mock components in EUI's own testing environments, use `jest.mock()` manually._ ### Using the mock namespace Component mocking relies on using the `[name].testenv.*` namespace for identification. The mocked module will replace the standard import in the `test-env` build. Both `index` files and individual component files can mocked. ### Mapping all module exports The rendered output of a mocked component is at the author's discretion, however, all public exports from a module must be preserved in the mock file. Note that this does not apply to exported TypeScript types and interfaces, which will always be derived from the original component file. --- ### Contributing To Eui Testing Visual Regression Testing (`wiki/contributing-to-eui/testing/visual-regression-testing.md`) # Visual regression testing EUI uses [Playwright Test Runner](https://playwright.dev/) with [`jest-image-snapshot`](https://github.com/americanexpress/jest-image-snapshot) for component visual regression testing. Tests run against a live Storybook instance and compare screenshots of stories against previously approved reference images. Visual regression tests run automatically on every pull request against the Storybook build from that pipeline, served locally on the VRT agent (the same files that are deployed as the preview). When differences are found, a diff table is posted as a PR comment and a Buildkite block step appears for human approval before baselines are updated. > [!IMPORTANT] > VRT runs in **CI** which owns the baselines and auto-commits them to your PR. Run it locally only when you really need to verify that many stories render as expected. ## Running VRT locally Make sure you have [Docker](https://docs.docker.com/get-docker/) installed and running. It's used to take screenshots in a Linux environment matching CI. Run the visual regression tests: ```shell yarn workspace @elastic/eui test-visual-regression ``` Locally this builds and serves a static Storybook (like CI) and rebuilds it each run, so no dev server is needed and every run reflects your current stories. To test against a specific URL instead (e.g. a deployed PR preview): ```shell yarn workspace @elastic/eui test-visual-regression -- --url https://eui.elastic.co/pr_1234/storybook ``` ### Static build vs. dev server The static build is served from flat files (no HMR) which keeps `networkidle` settling instantly. The dev server's HMR can otherwise stall it under emulation and make stories time out (see [Troubleshooting](#every-story-fails-with-pagewaitforloadstate-timeout-30000ms-exceeded)). The build happens inside the container (Linux, matching CI) and is reused across variants. ```shell # Reuse the existing build for fast iteration (skip the rebuild) yarn workspace @elastic/eui test-visual-regression -- --no-build # Use the dev server instead (requires `yarn storybook --no-open` running) yarn workspace @elastic/eui test-visual-regression -- --no-static ``` `--static`/`--build` default locally and are ignored when `--url` is set. ## Updating baseline screenshots ```shell # Update all baselines yarn workspace @elastic/eui test-visual-regression update # Update baselines against a specific URL yarn workspace @elastic/eui test-visual-regression update -- --url https://eui.elastic.co/pr_1234/storybook ``` Reference images are stored in `packages/eui/.vrt/reference/`. ## Variants Each story is snapshotted under multiple **variants** to catch e.g. responsive-layout regressions. Every variant produces its own baseline file, suffixed with the variant name: packages/eui/.vrt/reference/ navigation-euibutton--playground-desktop.png navigation-euibutton--playground-mobile.png The test-runner is invoked once per variant (similar to [Playwright projects](https://playwright.dev/docs/test-projects)), so each variant runs in its own process and browser context with the viewport applied before the story renders. Variants are defined in [`.storybook/vrt-variants.json`](https://github.com/elastic/eui/tree/main/packages/eui/.storybook/vrt-variants.json). CI runs one variant per parallel job. Locally, [`scripts/test-visual-regression.js`](https://github.com/elastic/eui/tree/main/packages/eui/scripts/test-visual-regression.js) reads that file and sets `VRT_VARIANT` for each run. Current variants: | Variant | Viewport | |---|---| | `desktop` | 1440 × 900 | | `mobile` | 390 × 844 | ### Skipping specific variants If a story can't render correctly under a particular variant, opt out of just that variant by passing an array to `parameters.vrt.skip` (see [Skipping stories](#skipping-stories)). The story still runs under the remaining variants. ## Filtering stories Pass any [`test-storybook`](https://storybook.js.org/docs/writing-tests/test-runner) flags after `--`. Jest path filters need `--` before the pattern: ```shell # By story name yarn workspace @elastic/eui test-visual-regression -- -- euibutton # By story file yarn workspace @elastic/eui test-visual-regression -- -- --testPathPattern=button.stories # By tag yarn workspace @elastic/eui test-visual-regression -- --includeTags vrt-only yarn workspace @elastic/eui test-visual-regression -- --excludeTags skip-vrt ``` The wrapper runs both variants. For one variant only: ```shell VRT_VARIANT=desktop yarn workspace @elastic/eui test-storybook -- euibutton ``` ## Skipping stories Set `parameters.vrt.skip` to opt a story out of VRT. Leave a comment explaining why. - `skip: true` skips the story under **all** variants. - `skip: ['mobile']` skips only the listed variants; the story still runs under the rest. ```tsx export const MyStory: Story = { parameters: { vrt: { // Skipped: this story is interaction-only, not a visual state skip: true, }, }, }; export const MobileUnsupported: Story = { parameters: { vrt: { // Skipped on mobile: the toolbar control is hidden below this breakpoint skip: ['mobile'], }, }, }; ``` Skipping a variant also skips the story's `play` body for that variant, so e.g. interactions don't run at a viewport the story isn't built for. When you add `vrt.skip` to a story that previously had a baseline, manually delete the affected snapshot files from `packages/eui/.vrt/reference/` (all variants for `true` or just the listed ones for an array). ## Using non-default selectors By default the test runner screenshots `#story-wrapper > *`. For components that render outside the story wrapper (portals, popovers, dropdowns) specify a custom selector in `parameters.vrt.selector`. Predefined selectors are exported from [`.storybook/vrt.ts`](https://github.com/elastic/eui/tree/main/packages/eui/.storybook/vrt.ts): ```tsx import { VRT_SELECTORS } from '../../../.storybook/vrt'; export const Open: Story = { parameters: { vrt: { selector: VRT_SELECTORS.portal, }, }, }; ``` Available selectors: | Selector | Value | Use case | |---|---|---| | `VRT_SELECTORS.default` | `#story-wrapper > *` | Default (no need to set) | | `VRT_SELECTORS.textOnly` | `#story-wrapper` | Components rendering a text node | | `VRT_SELECTORS.portal` | `page` | Portalled elements (popover, tooltip, dropdown); takes a full-page screenshot | ## Using interactions for specific states Wrap play functions with `playDecorator` when they need to reach elements outside the story wrapper (e.g. portals). It injects `bodyElement` (`document.body`) into the context so `within(bodyElement)` can query portal content. ```tsx import { userEvent, waitFor, within, expect } from '@storybook/test'; import { VRT_SELECTORS, playDecorator } from '../../../.storybook/vrt'; export const OpenDropdown: Story = { parameters: { vrt: { selector: VRT_SELECTORS.portal }, }, play: playDecorator(async (context) => { const { canvasElement, bodyElement } = context; // canvasElement: content inside the story wrapper const canvas = within(canvasElement); // bodyElement: use this to reach portalled elements const body = within(bodyElement); await userEvent.click(canvas.getByRole('combobox')); await waitFor(() => { expect(body.getByRole('listbox')).toBeVisible(); }); }), }; ``` By default the play function is skipped when not running under Playwright (i.e. in the Storybook UI). Pass `false` as the second argument to run it everywhere: ```tsx play: playDecorator(async (context) => { ... }, false) ``` ## Authoring stable stories VRT compares screenshots pixel-for-pixel (4-pixel allowance for subpixel diff), so anything non-deterministic (network requests, animations, randomness, timing or capturing the wrong element) produces false diffs or flaky failures. The test-runner already neutralizes several sources globally: - CSS animations are paused before the screenshot (`animations: 'disabled'`) and `prefers-reduced-motion: reduce` is emulated. - The runner waits for the page to be ready: for all `` elements to finish loading before capturing, for all fonts to be ready and for layout to be stabilized. - Failed screenshots are retried automatically. Some common failures and how to fix them: ### Only the first element is captured (fragment roots) The default selector `#story-wrapper > *` screenshots the **first child element** of the wrapper. A `render` function or decorator that returns a fragment with multiple siblings therefore captures only the first one and clips the rest: ```tsx // ❌ Only the first is captured render: () => ( <> ), // ✅ Wrap in a single element so the whole set is captured render: () => (

), ``` This also applies to decorators that add sibling content (e.g. wrapping the story in explanatory text) - wrap them in an element, not a fragment. ### Portalled content isn't captured Popovers, tooltips, modals, flyouts and dropdowns render outside the story wrapper, so the default selector misses them. Use the portal selector to take a full-page screenshot (see [Using non-default selectors](#using-non-default-selectors)): ```tsx parameters: { vrt: { selector: VRT_SELECTORS.portal } }, ``` ### Overlays captured before they finish opening An overlay opened on mount (through `isOpen` or initial state) may not be rendered/positioned when the screenshot fires, producing a blank or half-positioned capture that flakes. Add a `play` that waits for it to be visible: ```tsx import { within } from '../../../.storybook/test'; import { playDecorator } from '../../../.storybook/vrt'; export const Open: Story = { parameters: { vrt: { selector: VRT_SELECTORS.portal } }, play: playDecorator(async ({ canvasElement }) => { await within(canvasElement).waitForEuiPopoverVisible(); }), }; ``` For portalled panels you can also assert against `bodyElement`: ```tsx play: playDecorator(async ({ bodyElement }) => { await waitFor(() => expect(bodyElement.querySelector('[data-popover-open]')).toBeVisible() ); }), ``` ### Remote assets (images, avatars, fonts) Never reference remote URLs (`placehold.co`, `images.unsplash.com`, `picsum.photos`, `gravatar` etc.). Network fetches are slow and unreliable in CI, causing instability. Inline the asset as a `data:` URI instead: ```tsx const svg = ``; ``` If a story genuinely needs a real raster image (e.g. the `EuiImage` showcase), either bundle a committed local asset or `vrt.skip` the story. ### Randomized or time-based data `faker` without a seed, `Math.random()`, `Date.now()` and `new Date()` render different output on every run. Pin them: ```tsx import { faker } from '@faker-js/faker'; faker.seed(123); // consistent data across runs ``` Use fixed dates/values for anything rendered (e.g. `date="January 1st 1970"`). ### Oversized stories Stories that render hundreds of rows/items produce very tall screenshots that are slow to capture and can time out (especially under the `mobile` variant where responsive layouts stack every cell vertically). Keep datasets small. Note that `EuiBasicTable`/`EuiInMemoryTable` don't paginate `items` themselves, so passing a large array renders every row. ### Interaction- or behavior-only stories If a story exists to demonstrate behavior (focus return, callbacks, keyboard handling) and is visually identical to another captured story, it adds no VRT value and only risks flake - [skip it](#skipping-stories) with `vrt.skip` and a comment. ### Text-only components A bare text node can have zero height under `#story-wrapper > *`. Use `VRT_SELECTORS.textOnly` so the wrapper itself is captured (see [Using non-default selectors](#using-non-default-selectors)). ## Troubleshooting ### Every story fails with `page.waitForLoadState: Timeout 30000ms exceeded` `waitForPageReady` waits for `networkidle` on Playwright's own 30s timeout (separate from Jest's `--testTimeout`). The **dev server's** HMR keep the network busy. Under emulation it never goes idle in time, so *every* story times out and suites take 10-20 minutes. **Fix:** don't pass `--no-static` locally. The default [static build](#static-build-vs-dev-server) has no HMR, so `networkidle` settles instantly. ### VRT is slow or times out locally on Apple Silicon Local runs use a `linux/amd64` container to match CI. On Apple Silicon (arm64) that image is **emulated** and much slower than native, making large stories hang or time out: - **Enable Rosetta (recommended).** In Docker Desktop, turn on _Settings → General → "Use Rosetta for x86_64/amd64 emulation on Apple Silicon"_, and raise CPU/memory under _Settings → Resources_. Far faster than the default QEMU emulation while still `linux/amd64`, so screenshots stay byte-identical to CI. - **Run natively for quick checks only.** Dropping `--platform linux/amd64` runs the native arm64 image (no emulation, much faster). Renders are usually identical but architecture can introduce 1-2px anti-aliasing differences, so **don't commit baselines this way** - use it only to check stories run and let CI produce baselines. The Docker path in [`scripts/test-visual-regression.js`](https://github.com/elastic/eui/tree/main/packages/eui/scripts/test-visual-regression.js) also caps `--maxWorkers` and raises `--testTimeout` for headroom. ## CI pipeline architecture VRT runs automatically on every pull request as part of the `eui-deploy-docs` Buildkite pipeline. ```mermaid flowchart TD PR[Pull request] --> WS[Build and deploy website] PR --> SB[Build and deploy Storybook] SB --> VRT[Test visual regression] VRT --> R[Report visual regression] R -->|skip-vrt label| N[Notify] R -->|Pass, new stories| C1[Commit baselines\nto PR branch] R -->|Pass, no changes| N R -->|Fail, infrastructure error| N R -->|Fail, visual diffs found| D[Post diff table\nto PR comment] D --> B[Approve visual changes] B --> U[Update VRT baselines] U --> N C1 --> N WS --> N ``` CI commits baselines directly to the PR branch: - `chore(eui): add VRT baseline screenshots` - the PR adds new stories. Automatic, regardless of pass/fail. - `chore(eui): update VRT baseline screenshots` - after approving the *Approve visual changes* block step in Buildkite. A PR with both new and changed stories gets both commits, `add` first. Either commit retriggers CI. ### Skipping in a PR If VRT itself is broken and blocking merges, add the `skip-vrt` label to the GitHub PR. The VRT step will detect the label, exit without running any tests and the notify comment will clearly state that VRT was skipped. > [!WARNING] > `skip-vrt` doesn't run the test runner, so new stories don't get baselines. Be especially careful if you're adding it on your PR that introduces visual changes. The label is captured at build-trigger time. To affect an existing build, trigger a fresh one: - Comment `buildkite test it` on the PR - Push any new commit - Close and reopen the PR - Buildkite UI: click **New Build** (not "Rebuild", which reuses the original env) --- ### Packages Website Docs Content Accessibility (`packages/website/docs/content/accessibility.mdx`) --- sidebar_position: 6 --- # Accessibility This page shares common tips and tricks for writing accessible UI copy. It is not exhaustive and does not replace the official [WCAG 2.0 guidelines](https://www.w3.org/TR/2008/REC-WCAG20-20081211/#guidelines). Writing accessible UI copy is only one part of improving web accessibility. Check the [EUI documentation](https://eui.elastic.co/docs/utilities/accessibility/) for more accessibility guidelines. ## What is accessible content and why does it matter **Accessibility** for content means making sure that the content can be consumed properly, independently of how users choose or have to interact with it. Our users and readers are diverse, with different abilities and disabilities. They also interact with our content in different ways: screen readers, mobile devices, Braille, and so on. The list is long, and always evolving. As content authors, it is our responsibility to provide them with [perceivable, operable, understandable, and robust content](https://www.w3.org/TR/UNDERSTANDING-WCAG20/intro.html#introduction-fourprincs-head). ## Guidelines ✔️ **Make your content scannable.** A clear structure and meaningful words tell users if the feature or flow is relevant to them within seconds. ✔️ **Add alt text for all images, icons and media files.** Screen readers, Braille output devices, and search engines love concise, accurate alt text that describes what cannot always be displayed, viewed or heard on screen. | Inaccessible | | Accessible | | --------------------- | --- | ------------------------- | | Image of in progress rule creation form. | → | User is setting up a new threshold rule. | | Logs integrations | → | Integrations that let you to ingest logs. | ✔️ **Use plain language.** Clear, concise UI copy helps users perform tasks. Jargon and complex sentences can confuse or slow them down. You can find very helpful and detailed plain language guidance on the [plainlanguage.gov](https://www.plainlanguage.gov/guidelines/) website. | Inaccessible | | Accessible | | --------------------- | --- | ------------------------- | | Update the sourcerer selection to be the default detections data view. | → | Choose the default Security data view. | | **Cancel update rule?** You will lose changes to the rule. | → | **Discard rule changes?** Select **Discard** to reject these changes. | ✔️ **Use meaningful link text.** Descriptive text instead of "click here" or "read more" helps users understand what to expect when they open the link. Screen readers jump between links by generating a list of them, and spell out URLs. | Inaccessible | | Accessible | | --------------------- | --- | ------------------------- | | Click here for more information. | → | Learn more about indices. | | Create a query. Learn more. | → | Learn how to create an ES\|QL query. | ✔️ **Use device agnostic language.** Users can access content and products in many ways. We do not know if they use a mouse, keyboard, tablet, or another device. | Inaccessible | | Accessible | | --------------------- | --- | ------------------------- | | Type in your username and password. | → | Enter your username and password. | | Select a time range for the Alerts table. | → | Choose a time range for the Alerts table. | ✔️ **Avoid directional language.** Do not use above, below, left, right, and so on. All these terms assume that UI layouts never varies, that users can actually see the UI, and that they see it the way you think they do. Users might have disabilities or impairments that affect how they understand the UI. | Inaccessible | | Accessible | | --------------------- | --- | ------------------------- | | Complete the form below. | → | Complete the following form. | | Import values from a file by clicking the **Import values** button under the table. | → | Select **Import file** to import values from supported file types. | ## Words to avoid Refer to [Word choice](./word-choice.mdx) to learn more about words to avoid and their replacements. --- ### Packages Website Docs Content Adapt Tone (`packages/website/docs/content/adapt-tone.mdx`) --- sidebar_position: 4 --- # Tone Adapt the way you write to each situation users can face. During the users' journey with Elastic, there are times for excitement and discovery, but also times for help, support, and empathy. ## Stimulating **Attributes** We're proud to show new and cool stuff. Be: - Motivational - Excited - Enthusiastic When using this tone, you may: - Use exclamation marks, but sparingly. - Take time to help the user understand how this feature benefits them. - Use visuals to support your text. **When to use?** Although it can be very visible because of the way it's written and the UI elements it shows in, the **stimulating** tone is used **quite rarely** overall. We use it when we want to show new things to users, especially in: - Product tours - New feature announcements ## Informational **Attributes** E=MC². Be: - Direct - Straight to the point - Neutral When using this tone: - Use a minimum of words. - Write for scanning and help users quickly locate what matters to them. - Use action verbs to: - Label selection controls. - Describe what settings do or what to do with a setting. - Use clear nouns for - menus, form field names **When to use?** The **informational** tone is the **most used** one. It is everywhere in the UI, and sometimes seems so normal that we forget about it. Yet, it is very important! We use it for naming and describing things: - Menus, titles, setting names, hint text, placeholders, introductions, and descriptions - In-product assistance (tooltips, help popovers, setup guides, syntax references, etc.) - Information callouts - Confirmation modals - Calls to action (buttons and links) - Event logs ## Supportive **Attributes** Something might be wrong and requires attention. Let us help you. Be: - Reassuring - Serious - Urgent When using this tone, you may: - Be more action-oriented than usual to offer direct paths to users. - Focus on what went wrong. Don't be apologetic. - Help users learn how something happened, how to prevent it, how to fix it. - Provide clear actions, or clearly state it if there's no action needed. **When to use?** The **supportive** tone is used **sparingly** overall and is usually shown in places that draw the user's attention, for example in warnings and error messages. We use it when notifying users of things that require attention, especially in: - Errors - Licensing or billing-related content - Vulnerability and remediation content - Warnings and cautions - Upgrade and deprecation notices ## Stern **Attributes** We don't advise this action, but you're the master of your destiny. Be: - Deterring - Heavy with caution - Advisory When using this tone, you may: - Use stronger words that highlight possible negative effects. - Format the content in a way that make the risks stand out. **When to use?** The **stern** tone is **rarely** used. Reserve it for very specific cases, and for advanced or administrative features. We use it when insisting on the high risks an action could pose, especially in: - Danger type of warnings - Unsupported actions --- ### Packages Website Docs Content Inclusivity (`packages/website/docs/content/inclusivity.mdx`) --- sidebar_position: 7 --- # Inclusivity This page provides guidelines for writing inclusive UI copy for product content but it's not exhaustive. ## What is inclusive content and why does it matter **Inclusivity** for content means making sure that the content we serve reflects the diversity of our community, respects it, and promotes positive change. ## Guidelines ### Write for an international audience Our products use American English (en_US) as a standard for written content. Yet they are used, read by persons all around the globe, for whom English is not always their primary language. Our content must take that into account. ✔️ **Aim for simplicity.** Indeed, we are a technical company, writing for technically-savvy users. However, it benefits everyone if we try to keep our writing as simple as possible. * **Short sentences** - They leave less space for interpretation. They are easier to scan, read, and translate. * **Plain language** - Use active voice, present tense, using examples, and so on. Some of these guidelines might already look familiar. Several countries have [plain language initiatives](https://www.plainlanguage.gov/guidelines/) to promote clearer communication. Do your best to embrace these guidelines and focus on the message. * **Negation** - It is easier to say what something IS versus what it is NOT. When you add a negative construction, it takes the reader longer to parse the meaning of the phrase. For example, instead of saying "You cannot access the content without signing up", say "Sign up to access the content." * **Words with multiple meanings** - Don't skip helper words if they make the sentence clearer and easier to read. In UI copy, we try to be as literal and unambiguous as possible to ensure that it can be easily consumed by our users from around the globe. One way to achieve that is to choose words that have fewer meanings, especially when a word's intended meaning is not its primary meaning. ✔️ **Be aware of differences and diversity in content and examples.** Different people are used to different names, currencies, date and time formats, different units of measurement (like for temperature, distance, speed), and so much more. * Avoid ambiguous values, like `04/05/06` for a date. Is it May 4 or April 5, and which year? `11/17/1987` leaves less room for interpretation if the exact format is not specified nearby. * If there is no obvious example standard (RFC) to follow, try to be diverse to represent our audience. ✔️ **Avoid idioms or expressions that are not commonly known, a.k.a regionalisms.** In our Elastic documentation we aim for a fun, friendly, and sometimes quirky tone. To achieve that, it can help to use informal, playful language. However, we also have to be careful that our text is as inclusive as possible, so we try to avoid expressions that might be unknown or opaque for some users. Here are a few examples of what to avoid: * Idioms (for example, _It's a piece of cake_ or _So far so good_) * Regional expressions (for example, _G'day!_, _Y'all_, or _eh_) * Sports expressions (for example, _touched base_ or _threw a curve ball_) * Pop culture references (for example, _Elvis has left the building_ or _Same bat-time, same bat-channel_) We're all pretty good at avoiding these, but there's one problematic type of expression that sometimes shows up in UI copy. Latin terms and abbreviations are a common source of confusion, particularly for people whose first language does not have Latin roots. Here are some terms to avoid and suggested alternatives: | Avoid | | Use instead | --- | --- | --- | _e.g._ (exempli gratia) | → | _for example_ | | _etc._ (et cetera) | → | _and more_ or _and so on_ | | _i.e._ (id est) | → | _that is_ | | _via_ | → | _by way of_, _by means of_, or _through_ | ✔️ **Aim for readability.** Tools like the [Hemingway App](https://hemingwayapp.com/) can help you make content simpler. Be conversational, but prioritize clarity. ### Use gender-neutral language Writing gender-neutral mainly consists in avoiding gender bias and word choices implying that one gender is the norm. ✔️ **Pronouns.** In the UI, this can be avoided by addressing users directly. When it's not possible, use *they*/*their*, even for singular. There's more than one gender, and it's not binary either. ✔️ **Biased words and expressions.** Guys, mankind, policeman... Words that we're all used to hear and use. But the default is not male. Most expressions and words that perpetuate this bias (that exists in many cultures and languages!) can be replaced with neutral alternatives or synonyms: Folks, humanity, police officer... ### Avoid violent, offensive, ableist terminology Earlier in this page, we discussed avoiding ambiguous terms, especially when a word's intended meaning is not its primary meaning. Other types of words and phrases best avoided are: * buzzwords (_incentivize_, _synergies_) * superhero terms (_rock star_, _wizard_, _ninja_) * violent imagery (_crush the competition_) * non-specific superlatives (_unrivaled_, _unparalleled_, _world class_) Some words have nuances that fall into the above categories, which may cause them to be misinterpreted. Here are some alternatives: | Avoid | | Use instead | --- | --- | --- | Abort | → | _stop_, _cancel_, or _end_ | | Boot | → | _start_ or _run_ | | Execute | → | _run_ or _complete_ | | Hack (noun) | → | _tip_ or _workaround_ | | Hack (verb) | → | _configure_ or _modify_ | | Hit (verb) | → | _click_ or _press_ | | Hit (noun) | → | _visits_ (as in _website visits_) | | Invalid | → | _not valid_ or _incorrect_ | | Kill | → | _cancel_ or _stop_ | | Terminate | → | _stop_ or _exit_ | --- ### Packages Website Docs Content Language (`packages/website/docs/content/language.mdx`) --- sidebar_position: 5 --- import { EuiFlexGroup, EuiButton, EuiSideNav, htmlIdGenerator, EuiIcon, EuiCallOut, } from '@elastic/eui'; # Language Guidelines for using consistent spelling and terminology in the UI. ## Spelling Use American English when writing UI copy. American English is a version of the English language used in the United States. It's sometimes called United States English or U.S. English. Certain words are spelled differently in American English and British English. You'll find some of these key spelling differences in the following sections. ### Verbs that end with 'ize' or 'yze' In American English, verbs that end with 'ize' usually end with 'ise' in British English. Similarly, verbs that end with 'yze' in American English usually end with 'yse' in British English. | American English | British English | | ------------- |:-------------:| | organize | organise | | authorize | authorise | | analyze | analyse | ### Nouns that end with 'or' In American English, nouns that end with 'or' usually end with 'our' in British English. | American English | British English | | ------------- |:-------------:| | flavor | flavour | | color | colour | | behavior | behaviour | ### Nouns that end with 'ense' In American English, nouns that end with 'ense' usually end with 'ence' in British English. | American English | British English | | ------------- |:-------------:| | license | licence | | defense | defence | | pretense | pretence | ### Nouns that end with 'og' In American English, nouns that end with 'og' usually end with 'ogue' in British English. | American English | British English | | ------------- |:-------------:| | dialog | dialogue | | catalog | catalogue | | epilog | epilogue | ## Case and capitalization This goes for navigation menus, titles and headers, buttons, and so on. Use **sentence case** by default for UI copy, including actions, views, settings, section headers, and dialog titles. Sentence case is easier to read, even in headings, and helps branded names stand out. It also makes those names easier to recognize and preserve when localizing an interface. Title Case can feel more formal, so don't use it just to make a label look prominent. Reserve **Title Case** for proper names: branded products, apps, and features such as Entity Analytics and Machine Learning. A useful check is whether you'd refer to the item by that name in a product announcement, rather than using the words to describe what a section contains. For example, Stack management, GenAI settings, Budgets and notifications, API keys, and Trust management are descriptive labels, so use sentence case. Keep a proper name's established capitalization wherever it appears, and use sentence case for the surrounding words, as in "Open in Entity Analytics" or "Entity Analytics settings." Even with sentence case, make sure to capitalize the following terms and expressions: - [Branded terms](https://brand.elastic.co/302f66895/p/194a3b-writing-style-guide/t/159934) like solution and application names. For example, always write Elastic Observability, **not** elastic observability. - Acronyms, such as URL and API. Note that some names don't need to be capitalized when they're used as common names. For example, **Elastic Cloud Serverless** and **our serverless architecture** are both correct. | UI text | Casing | Why | | --- | --- | --- | | Entity Analytics | Title Case | Feature name | | Add data | Sentence case | Action, not a name | | Open in Entity Analytics | Sentence case, with the name unchanged | Sentence-case action containing a capability name | | Create Entity Analytics dashboard | Sentence case, with the name unchanged | "Entity Analytics" is a name; "dashboard" is generic | | Entity Analytics settings | Sentence case, with the name unchanged | "Settings" is a generic descriptor | | Add to case | Sentence case | "Case" is a generic object, not a name | | Open in Cases | Sentence case, with the name unchanged | "Cases" is the app name | Check for new data Check For New Data Add data Open in Entity Analytics Add Data Open in entity analytics , items: [ { name: 'Overview', id: htmlIdGenerator('overviewDo')() , onClick: () => {}}, { name: 'Entities', id: htmlIdGenerator('entitiesDo')() , onClick: () => {}}, { name: 'Settings', id: htmlIdGenerator('settingsDo')() , onClick: () => {}}, ], }, ]} /> , items: [ { name: 'Overview', id: htmlIdGenerator('overviewDont')(), onClick: () => {}}, { name: 'Entities', id: htmlIdGenerator('entitiesDont')() , onClick: () => {}}, { name: 'Entity Analytics Settings', id: htmlIdGenerator('settingsDont')() , onClick: () => {}}, ], }, ]} /> ## Punctuation ### Ellipsis Only use ellipsis for truncated text or situations that require the user to wait. - **Do:** Page loading... **not** Elastic offers many features such as Dashboards, Machine Learning, Synthetics... ### Exclamation mark Avoid exclamation marks in most cases. A single exclamation mark when sharing exciting news may be appropriate. ### Oxford comma Use the Oxford comma before the final item in a list. - **Do:** Elastic's solutions are Elasticsearch, Observability, and Security **not** Elastic's solutions are Elasticsearch, Observability and Security ### Periods (full stops) Use periods with: * description text * messages * notifications * list items that are complete sentences Don't use periods with: * headers * titles * placeholders * list items that are incomplete sentences ## Contractions Use contractions if they make your text flow more naturally, such as "didn't" instead of "did not" and "can't" instead of "cannot." Didn't find what you were looking for? Did not find what you were looking for? ## Vocabulary Check [Word choice](./word-choice.mdx) for guidance on specific terms to use or to avoid. --- ### Packages Website Docs Content Style (`packages/website/docs/content/style.mdx`) --- sidebar_position: 3 --- # Voice and writing style Our **Voice** represents the personality we want to convey through the UI copy in our products. The following principles define the foundation of our voice. ## Conversational Real people, talking to real people. | ✔️ Be... | How? | |--------------------|-----------------------------------------------------------------------------| | User-focused | Address users directly. Don't abuse possessive markers like "yours".[1] | | Plainspoken | Be conversational, yet professional. Write close to how you'd talk. Use contractions and active voice. | | Inclusive | Write for all audiences. Our users are from everywhere. Don't use terms that might discriminate or offend and avoid complex language for non-native English speakers such as phrasal verbs. | | Empathetic | Write what matters to users. Use words that you and users normally use. | > [1] Sometimes, we give the user full ownership of an action. In that case, it's acceptable to use "I" and "my". For example, for a legal agreement checkbox "I agree to follow the terms of service". We can also use "We" when talking about actions Elastic takes for users. ## Practical Get the user's job done. | ✔️ Be... | How? | |-------------|-----------------------------------------------------------------------------------------| | Timely | Help users when it's needed. Not everything is critical to describe in more details or at once. Make information discovery progress at the same pace as the user. | | Informative | Ensure all content serves a purpose and is not just decoration. Be straight to the point. It's not mandatory to have help text and descriptions for everything.| | Action-oriented | Whenever possible, drive actions and support user intent with action verbs.| | Precise | Avoid using verbs or determiners alone without a noun in buttons and action menus to add clarity. For example, prefer "Save dashboard" over "Save". Or "this setting" over "this".| | Consistent | Use the same terminology to mean the same thing. Make sure spelling, capitalization, punctuation, labels, and use of abbreviations are all consistent.| | Succinct | Shorten the content to something meaningful and scannable, without sacrificing clarity. Delete unnecessary or vague wording like most adverbs. | ## Authentic Inspire trust. | ✔️ Be... | How? | |-------------|------------------------------------------------------------------------------------| | Optimistic | Help users progress and succeed with what they are doing right now. Do not blame them in case of errors and instead let them know what to do and encourage actions. | | Confident | Encourage best practices but let users choose their path. Provide them with just enough information to help them make informed decisions. | | Transparent | Help users connect the dots without jargon or vague statements. Provide values or realistic ranges to set the right expectations. For example "This operation can take up to 5 minutes" instead of "Wait a few minutes while we get you set up". | --- ### Packages Website Docs Content Word Choice (`packages/website/docs/content/word-choice.mdx`) --- sidebar_position: 8 --- # Word choice Find the right term to use in your UI copy. ## Use these preferred words and terms Use these words and terms in the scenarios described in the following table: | Word | Usage notes | | ------- | ------------ | | **add** | Use for establishing a new relationship. Often used in create-then-add scenarios. Create a dashboard, then add a visualization. In button labels, always follow _add_ by an object. Remove is the correct opposite. | | **cancel** | Use to stop an action without saving pending changes. | | **can't** | Use to indicate you don't have the ability to do something. Often confused with _unable_. | | **create** | Use for creating an object from scratch. In button labels, always followed by an object. Do not use _create new_. Delete is the correct opposite. | | **delete** | Use when deleting data that users can no longer retrieve. Create is the correct opposite. | | **edit** | Don't use _change_ or _modify_. Edit is the better choice for localization. | | **enter** | Use when the user enters text. Don't use _type_. | | **later** | Use when referring to versions of the product. For example, Elastic Stack 8.13 and later. | **open** | Use when opening an application or program. Don't use _launch_. | | **press** | Use _press_ for keyboard keys. Don't use _hit_. | **remove** | Use when removing a relationship, but not permanently deleting the data. For example, you remove a visualization from a dashboard. Add is the correct opposite. | | **select** | _Select_ is preferred over _choose_. | | **use**| Use instead of _utilize_ and _make use of_. | | **view** | Use instead of _see_ because _view_ is more inclusive. | ## Avoid these words and terms This section includes terms that you should avoid in most instances. These terms might be offensive, non-inclusive, unclear, or unnecessary. Use the alternate suggestions in the following tables or a more specific term. ### Latin abbreviations Latin abbreviations can be unclear. Use the following suggestions instead: | Word | Usage notes | | ------- | ------------ | | **e.g.** | Use _for example_ or _such as_ instead. | | **i.e.** | Use _that is_ instead.| | **via** | Use _with_, _by using_, or _through_ instead. | ### Directional language Directional language does not meet accessibility requirements and you should avoid it, especially as the only way to find an element in the UI. Use the following suggestions instead: | Word | Usage notes | | ------- | ------------ | | **above** | Use a link, _previous_, or _preceding_ instead. | | **below** | Use a link or _following_ instead| ### Nouns created from verbs Avoid using nouns created from adjectives or verbs. These words often make text unnecessarily complex. For example: - Use _choose_ instead of _make a choice_. - Use _register_ instead of _complete your registration_. - Use investigate instead of _conduct an investigation_. ### General words and terms to avoid Avoid the following words and terms, and use the suggestions instead: | Word | Usage notes | | ------- | ------------ | | **abort** | Use _shut down,_ _cancel,_ or _stop_ instead. | | **as well as** | Use _and_ instead. | | **blacklist** | Use _blocked list_ instead. | | **boot** | Use _start_ or _run_ instead. | | **bottom left, bottom right** | Use _lower left_ or _lower right_ instead. Hyphenate when using as an adjective. For example, lower-left corner. | | **choose** | Use _select_ instead. See Words for interacting with UI| | **disable** | Use _turn off_, _block_, or _hide_. | | **enable** | Use _turn on_ or _allow_. | | **easy**, **easily** | It can be frustrating for users to think that something is easy, but then struggle to do the task. Typically the same meaning can be conveyed without this word.| | **execute** | Use _run_ or _start_ instead.| | **hack** | For a noun, use _tip_ or _work-around_ instead. For a verb, use _configure_ or _modify_. | | **hit** | For a noun, use _visits_ (as in web visits). For a verb, use _select_ or _press_.| | **hear**, **hear about** | Use _learn_ instead. | | **impact** | Don't use impact as a verb. Use _affect_ instead. | | **in order to** | Use simple verbs like _to_ instead. | | **invalid** | Use _not valid_ or _incorrect_ instead. | | **just** | Don't use before a command, like "_just_ click here." | **launch** | Use _open_ instead. | | **ok** | Don't use when labeling buttons. Use words that explain the action instead, for example, _Delete rule_. | | **normal**, **normally** | Use _usual_ or _typical_ instead. For _normally_, use _usually_, _typically_, or _generally_ instead. | **please** | In most cases, _please_ is unnecessary. Only use when the user must wait or do something inconvenient. | | **simple**, **simply** | Unnecessary because it doesn't add any information or value.| | **sorry** | Only use _sorry_ in error messages that cause serious problems for the user. | | **success** | Unnecessary because _success_ is generally implied. | | **terminate** | Use _stop_ or _exit_ instead.| | **type** | Use _enter_ because there is typically more than one way to enter text. | | **top left, top right**| Use _upper left_ or _upper right_ instead. Hyphenate when using as an adjective. For example, upper-left corner. | | **utilize** | Don't use _utilize_ when you mean _use_. | | **whitelist** | Use _allow list_ instead. | ## Use caution with these words and terms These words and terms might be appropriate in some situations and inappropriate in others. Only use them when appropriate. | Word | Usage notes | | ------- | ------------ | | **app**, **application**| Use only when needed for clarity. Otherwise, a Kibana application name can stand alone. App is a well-known abbreviation for application and is preferred. | | **begin** | Use context to decide between _begin_ and _start_. For example, _begin a procedure_, _begin an analysis_, or _begin an installation_ are common phrases. Similarly, _start a program_, _start an engine_, or _start a timer_ are frequently used. _Start_ is considered less formal than _begin_. _End_ is the correct opposite of _begin_.| | **can** | Use for capability. Rewrite as an action if possible. For example, instead of _you can add..._ use _add..._. | | **click** | Acceptable to use when describing mouse actions. Otherwise, use verbs that work with multiple devices, such as _select_. | | **clone** | Use when creating a copy that is linked to the original. Often confused with _copy_ and _duplicate_. | | **copy** | Use when the file is added to a clipboard and can be pasted in a new location. Often confused with _clone_ and _duplicate_. | | **disable** | Don't use to describe something that is broken. Use _inactive_, _unavailable_, _deactivate_, _turn off_, or _deselect_, depending on the context.| | **duplicate** | Use when immediately creating a copy of an object in the same location as the original. Often confused with _copy_ and _clone_. | | **kill** | Use _cancel_ or _stop_ unless the actual command is `kill`. | | **may** | Use _may_ for permissibility. Use _can_ for capability. Use _might_ for possibility. | | **start** | Use context to decide between _start_ and _begin_. For example, _start a program_, _start an engine_, or _start a timer_ are common phrases. Similarly, _begin a procedure_, _begin an analysis_, or _begin an installation_ are frequently used. _Start_ is considered less formal than _begin_.| | **unable** | Unable means not being able to perform an action. Often confused with _cannot_. | --- ### Packages Website Docs Dataviz Accessibility Features (`packages/website/docs/dataviz/accessibility-features.mdx`) --- sidebar_position: 3 --- import useChartBaseThemeSource from '!raw-loader!./use_chart_base_theme'; # Accessibility features import VersionBadge from './version_badge'; ```mdx-code-block import * as ElasticCharts from '@elastic/charts'; import { useChartBaseTheme } from './use_chart_base_theme.ts'; ``` Elastic Charts provides some accessibility features for all users. **Available a11y-related features** * Chart titles * Chart descriptions * Chart data in tabular form\* * Texture fill\* * Semantic groupings\* \*Not all chart types that may benefit from this feature have it implemented as of yet ## Titles `ariaLabel` and `ariaLabelledBy` props can be set through the `` component. `ariaLabel` takes a string label which will be visually hidden whereas the`ariaLabelledBy` prop can tie the chart to other accessible elements elsewhere in your app. ```tsx <>

Days of the week: weekdays vs weekends

``` If using `ariaLabel`, you can set a heading level for it by passing in `ariaLabelHeadingLevel`. `h1` through `h6` are valid options (`p` is the default). You may want to set a heading level if there are multiple charts on the page but you want to draw attention to a select few or if a specific chart is the main content of the page. ```tsx ``` ## Descriptions `ariaDescription` and `ariaDescribedBy` props can be set through the `` component.`ariaDescription` takes a string description which will be visually hidden whereas `ariaDescribedBy` prop takes an `id` that you have rendered elsewhere in your app. ```tsx ``` :::warning `ariaDescribedBy` will override `ariaDescription` if both are specified. ::: `ariaUseDefaultSummary` is a boolean defaulted to `true`. The default summary is bare bones and only reports the chart type(s). Some chart types provide more information but today that is only Gauge and Goal charts. If you are passing in a custom description, you can disable this prop. ```tsx <>

Days of the week: weekdays vs weekends

Bar chart with two bars. Bar one is labelled weekdays and has a value of 5. Bar two is labelled weekends and has a value of 2.

``` ## Tables A visually hidden data table is rendered for some chart types. `ariaTableCaption` sets a custom caption on that table. Consider the table caption supplementary to the description. Use it to fill in any gaps that might be created when converting the chart to a tabular format. :::note In version 64.1.0, data tables are only available for **partition charts**. Partition charts include: sunburst, treemap, icicle, flame, mosaic, and waffle. ::: ``` /* Detailed source-code truncated for AI context efficiency. */ ``` For the provided example, a visually hidden data table is rendered with the caption we passed on `ariaTableCaption`. ```tsx

There is a great variety of reported favorite fruit

Chart type:: sunburst chart

After Clementine (22), individual results are not labelled as the segments become too small
Label	Value	Percentage
Apple	100	27%
Durian	1	0%