Accessibility
Screen reader only
Using EuiScreenReaderOnly hides the wrapped element from the page, but keeps it accessible for screen readers to provide more context. It should be used primarily to mask text and requires the child to be a single React element for cloning.
WebAIM recommendation for screen reader-only content
"In most cases, if content (particularly content that provides functionality or interactivity) is important enough to provide to screen reader users, it should probably be made available to all users." Learn more about invisible content
Using a screen reader, verify that there is a second paragraph.
Showing on focus
If the wrapped element is focusable, you must use the showOnFocus prop to visibly show the element to all users when focused.
Tab through the following example with your keyboard to verify the element is visible on focus.
Screen reader live region
Using EuiScreenReaderLive to announce dynamic content, such as status changes based on user interaction.
The configurable role and aria-live props default to status and polite respectively for non-intrusive but timely update announcements. When not using the default values, be sure to follow ARIA guidelines for role to aria-live mapping.
Also consider other live region guidelines, such as that live regions must be present on initial page load, and should not be in a conditional JSX wrapper.
Auto-focusing the live region on text change
The focusRegionOnTextChange prop will automatically focus the EuiScreenReaderLive region (causing screen readers to read out the text content) whenever children changes.
This is primarily useful for announcing navigation or page changes, when programmatically resetting focus location back to a certain part of the page (where the EuiScreenReaderLive is placed) is desired.
Using a screen reader, click the following navigation links and notice that when the new page is announced, focus is also set to the top of the body content.
Live announcer region Beta
EuiLiveAnnouncer is a new, experimental alternative to EuiScreenReaderLive for screen reader live region announcements.
Its API and behavior may change based on feedback and testing.
Both EuiLiveAnnouncer and EuiScreenReaderLive are designed for the same use cases: to announce dynamic content, such as nodifications or status changes based on user interaction.
The main drawback for live regions is that they must be present on initial page load before reading content updates. EuiLiveAnnouncer addresses this
by updating the content after the initial render to ensure an announcement is made when mounting a component.
Same as for EuiScreenReaderLive, EuiLiveAnnouncer supports configurable role and aria-live props which default to status and polite respectively for non-intrusive but timely update announcements.
If you're not using the default values, be sure to follow ARIA guidelines for role to aria-live mapping.
Main difference
EuiLiveAnnouncerwill announce the message when the component mounts (e.g., when it first appears in the DOM), as well as when the message changes.EuiScreenReaderLivewill only announce when the message changes, and will not announce the initial message on mount.
This means EuiLiveAnnouncer is especially useful for scenarios where you want to ensure an announcement is made immediately when a component is mounted, e.g. showing a notification or alert based on user interaction.
An additional difference is that EuiLiveAnnouncer can clear its message after a configurable timeout via clearAfterMs, which prevents stale
announcements and duplicated DOM content for screen reader users. Screen readers will continue reading the message even if it was already cleared.
Key differences between EuiLiveAnnouncer and EuiScreenReaderLive
Feature | EuiLiveAnnouncer | EuiScreenReaderLive |
|---|---|---|
Auto-clear message | Yes, after configurable timeout ( clearAfterMs) | No |
Announce on mount | Yes | No |
Announce on message change | Yes | Yes |
Focus on message change | No | Yes ( focusRegionOnTextChange prop) |
Handles rapid updates | Yes | Yes |
Output consistency | High | Medium |
API stability | Beta/experimental | Stable |
Skip link
The EuiSkipLink component allows users to bypass navigation, or ornamental elements, and quickly reach the main content of the page. It requires a destinationId which should match the id of your main content. If your ID does not correspond to a valid element, the skip link will fall back to focusing the <main> tag on your page, if it exists.
Tab through the following section to verify the Skip to content button is visible on focus.
Styles helpers
.euiScreenReaderOnly className
This utility class allows you to apply the screen reader only CSS styles directly to your component.
The next paragraph is hidden except for screen readers.
I am hidden except for screen readers
tsx code block:<p className="euiScreenReaderOnly" />
euiScreenReaderOnly() function
This function allows you to apply the screen reader only CSS styles directly to your component.
The next paragraph is hidden except for screen readers.
I am hidden except for screen readers
tsx code block: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 code block:css` &:focus { ${useEuiFocusRing('center', euiTheme.colors.accent)} } `
Props
EuiScreenReaderOnly
Prop | Description and type | Default value |
|---|---|---|
Prop children# | Description and type ReactElement to render as this component's content ReactElement<any, string | JSXElementConstructor<any>> | Default value Required |
Prop showOnFocus# | Description and type For keyboard navigation, force content to display visually upon focus/focus-within. boolean | Default value |
Prop className# | Description and type Type: string | Default value |
EuiScreenReaderLive
Prop | Description and type | Default value |
|---|---|---|
Prop isActive# | Description and type Whether to make screen readers aware of the content boolean | Default value true |
Prop children# | Description and type Content for screen readers to announce ReactNode | Default value |
Prop role# | Description and type
AriaRole | Default value status |
Prop aria-live# | Description and type
"off" | "assertive" | "polite" | Default value 'polite' |
Prop focusRegionOnTextChange# | Description and type On boolean | Default value false |
EuiLiveAnnouncer
Prop | Description and type | Default value |
|---|---|---|
Prop children# | Description and type Content for screen readers to announce ReactNode | Default value |
Prop role# | Description and type
AriaRole | Default value status |
Prop isActive# | Description and type Whether to make screen readers aware of the content boolean | Default value true |
Prop aria-live# | Description and type
"off" | "assertive" | "polite" | Default value 'polite' |
Prop clearAfterMs# | Description and type Sets a delay in ms before the live region is cleared. number | false | Default value 2000 |
EuiSkipLink
Prop | Description and type | Default value |
|---|---|---|
Prop destinationId# | Description and type Typically an anchor id (e.g. string | Default value Required |
Prop position# | Description and type Change the display position of the element when focused. "fixed" | "absolute" | "static" | Default value static |
Prop fallbackDestination# | Description and type If no destination ID element exists or can be found, you may provide a query selector For complex applications with potentially variable layouts per page, an array of string | string[] | Default value main |
Prop overrideLinkBehavior# | Description and type If default HTML anchor link behavior is not desired (e.g. for SPAs with hash routing), boolean | Default value |
Prop tabIndex# | Description and type When position is fixed, this is forced to number | Default value |
Prop fill# | Description and type Make button a solid color for prominence boolean | Default value |
Prop color# | Description and type Any of the named color palette options. Do not use the following colors for standalone buttons directly,
"text" | "accent" | "accentSecondary" | "primary" | "success" | "warning" | "danger" | "neutral" | "risk" | Default value |
Prop size# | Description and type Use size "s" | "m" | Default value |
Prop isDisabled# | Description and type Controls the disabled behavior via the native boolean | Default value |
Prop hasAriaDisabled# | Description and type NOTE: Beta feature, may be changed or removed in the future Changes the native Use e.g. when a disabled button should have a tooltip. boolean | Default value |
Prop style# | Description and type Type: CSSProperties | Default value |
Prop className# | Description and type Type: string | Default value |
Prop css# | Description and type Type: Interpolation<Theme> | Default value |
Prop element# | Description and type Type: "a" | "button" | "span" | Default value |
Prop iconType# | Description and type Any IconType | Default value |
Prop iconSide# | Description and type Can only be one side ButtonContentIconSide | Default value |
Prop isLoading# | Description and type Force disables the button and changes the icon to a loading spinner boolean | Default value |
Prop textProps# | Description and type Object of props passed to the This span wrapper can be removed by passing false | (HTMLAttributes<HTMLSpanElement> & CommonProps & { ref?: Ref<HTMLSpanElement>; 'data-text'?: string; }) | Default value |
Prop iconSize# | Description and type Type: "s" | "m" | Default value |
Prop aria-label# | Description and type Defines a string value that labels the current element. string | Default value |
Prop data-test-subj# | Description and type Type: string | Default value |
Prop isSelected# | Description and type Applies the boolean state as the boolean | Default value |
Prop fullWidth# | Description and type Extends the button to 100% width boolean | Default value |
Prop minWidth# | Description and type Override the default minimum width false | MinWidth<string | number> | Default value |
Prop contentProps# | Description and type Object of props passed to the wrapping the button's content CommonProps & EuiButtonDisplayContentType | Default value |
Prop type# | Description and type Type: "reset" | "submit" | "button" | Default value |
Prop href# | Description and type Type: string | Default value |
Prop onClick# | Description and type Type: MouseEventHandler<HTMLAnchorElement> | Default value |
Prop buttonRef# | Description and type Type: Ref<HTMLAnchorElement> | Default value |