Button
Buttons enable user actions and are crucial for forms, modals, toolbars, and interactive pages. These guidelines detail their optimal configuration and placement.
Buttons offer various types, sizes, colors, and properties. The best combination depends on placement, prominence, and state.
EuiButton is for primary and secondary actions, while EuiButtonEmpty is for tertiary or low-prominence actions.
Button types
Regular
Regular EuiButton can be used for two types of actions: primary and secondary. It has the fill property set to false by default, which is typically used for secondary actions, striking a balance between visibility and visual noise. They are less prominent than primary actions and can be used alongside them. Primary actions (CTAs) should be represented by filled buttons (fill: true).
Empty
Empty buttons are for complementary (tertiary) actions like close, cancel, filter, and refresh, which typically affect data presentation rather than modification. They reduce a button's visual importance and support xs
Icon
EuiButtonIcon is an icon-only button. Use display and size props to match standard buttons. The default appearance is xs, empty. Use only for common, intuitive actions with immediately understood icons (e.g., trash can for delete). aria-label is required for accessibility. Icon color inherits from the button's color property. Icon color is inherited from the button color property and, therefore, does not need to be set separately.
Accessibility
EuiButtonIcon requires an aria-label to express the meaning to screen readers.
Do: Use icon buttons for universal actions that are easy to understand.
Don't: Icons alone in a standard button look awkward and take too much space.
Button as link
Use EuiButton for actions and EuiLink for text-based navigation. Buttons and links have different semantic and technical implications. Buttons accept href (renders as <a>) or onClick (renders as <button>). Using both simultaneously is generally not recommended.
If you are creating a purely text-based link, like the one in the previous paragraph, use EuiLink instead.
Note
For more specific information on how to integrate EUI buttons with react-router, see this wiki page.
Style
Warning
Do not override button styles. EUI provides properties to manage color, size, and state to cover various use cases, ensuring consistent interactions.
Color and semantic
Buttons come in various colors, with primary, text, or danger being typical choices. Primary is the default.Danger, warning, and success buttons convey specific meanings:
- Danger: Negative, destructive action, critical attention.
- Warning: Caution, extra attention.
- Success: Positive, successfully-completed action, least attention.
Avoid direct use of semantic buttons unless they are part of existing EUI components. Direct use of danger (red) buttons is limited to confirming destructive outcomes, like deleting data, to maintain its elevated meaning.
Success (green) buttons indicate unsaved or unprocessed changes (draft or dirty state) to mitigate work loss. Do not rely solely on color for meaning; include a label or icon for accessibility and clarity.
Text color variant
Use text button color variants on action-heavy UIs to reduce visual noise. This variant has a unique bordered appearance for dense screens with many inputs, buttons, and tabular content, where shaded buttons would create visual clutter. See more on how to combine button variants below.
Size
Buttons default to a medium (m) size, suitable for most cases. Small (s) and extra small (xs) are also available. Stick with the default size unless necessary.
Extra small applies only to EuiButtonEmpty and EuiButtonIcon.
Do not mix button sizes within a group or row; maintain consistent height. Use s buttons in small containers, popovers, toasts, filter bars, and compressed forms for constrained spaces, not subjective design preferences. Use xs buttons for supplementary information alongside actions or within forms (see guidelines for writing help content). They are also used within other EUI components.
Do: Stick to the default pattern: a filled, primary button paired with an empty, but same-colored button.
Don't: Readability suffers when multiple colors and sizes are used.
Width
Button width is generally determined by content (label, icon, padding). Icon-only buttons are smaller and square. EUI sets a default minimum width for consistency, which should be overridden rarely. Use fullWidth buttons primarily in narrow forms or for mobile responsiveness; use sparingly in larger desktop viewports.
Do: Use full-width buttons in narrow forms.
Don't: Don't make buttons unnecessary wide in larger viewports.
Flush prop
The flush property is only available for EuiButtonEmpty. It removes padding, ensuring stricter alignment with surrounding content, especially at container edges where empty buttons might otherwise create a ragged line.
State
Disabled
Show a button in a disabled state when the action cannot be performed due to permissions, licensing, or data issues (e.g., invalid input). Consider whether the user needs to know the button exists; showing it indicates potential actions, while hiding it may lead to unawareness. Only hide buttons when the action's potential is immaterial. Do not show disabled buttons if the user is unlikely to perform the action. All button types have the same disabled state.
Loading
Always consider the button loading state due to potential performance slowdowns. Set isLoading to true to display a loading spinner. Not handling this state can lead to extra clicks and user frustration. Setting isLoading to true adds a spinner or swaps an existing icon for one, and disables the button. Renaming the button to "Loading…" is good practice. All button types have the same loading state.
Button labels
Button labels should clearly indicate the action, using action words and an object if context isn't clear (e.g., "Create dashboard"). Labels should not exceed three words; longer labels may be better as text links.
Preferred words
- Add X — Establishes a new relationship (e.g., "Add visualization"). Always followed by an object. Opposite: Remove.
- Cancel — Stops an action without saving. Never red; always an empty button.
- Create X — Creates a new object (e.g., "Create pipeline"). Always followed by an object. Opposite: Delete.
- Delete N items — Permanently deletes data. Opposite: Create. Not to be confused with Remove.
- Remove X — Removes a relationship without permanently deleting data (e.g., "Remove visualization"). Opposite: Add.
- Save / Save and complete — Carries out pending changes (e.g., "Save edits"). Can be green if final save action. Not to be confused with Add.
Words to be avoided
- New — Use ‘Add’ or ‘Create’.
- Ok — Use action-specific words.
- Yes / No — Use words that clearly explain the action.
Usage
Additional icons
Icons can serve as an addition to the text label to emphasize actions, but should be used sparingly. Icons work best on labels for binary actions, such as "Create" and"'Delete", or final actions, such as "Save".
Do: The arrow shows that there are more items to fill out, and the check icon indicates the final action.
Don't: Unnecessary icon just distracts the user, especially it is on the right and is hard to interpret.
Combining buttons
Primary and secondary actions typically use filled and default styles, respectively. Display one primary action button per layout to signal its importance. Not every page requires a primary action button. Use default buttons for secondary visual prominence, less prominent than primary CTAs, but still visually distinct. They can be used in layouts without a CTA.
Do: Use only one filled button per layout — the one you want the user to eventually complete.
Don't: Too many primary buttons will confuse the user.
Buttons adjacent to a primary CTA should be tertiary, presented as empty buttons. Tertiary actions are less consequential, exiting the flow or not changing data.
Do not use all three styles in the same button group. When multiple actions are grouped, use either secondary (default) or tertiary (EuiButtonEmpty) styles. Avoid mixing simple/empty buttons with icon-only buttons in one row.
Do: Stick to the default pattern: a filled, primary button paired with an empty, but same-colored button.
Don't: Readability suffers when multiple colors and sizes are used.
Use text color for buttons on visually dense screens. This reduces visual noise and emphasizes key actions, especially when primary or secondary CTAs are present.
Do: Use text buttons to reduce visual noise on dense screens with multiple actions.
Placement and order
Place buttons on the right in restricted-width containers (modals, popovers, bottom bars, flyouts). The user path is left-to-right, top-to-bottom, in a Z-shaped pattern. Place primary actions on the bottom right, where users finish scanning.
Do: Place the primary action on the bottom right with the secondary action on its left in modals.
Do: Always use buttons positioned to the right in popovers.
Place buttons on the left in unrestricted large-width spaces (page forms). Content is typically anchored left, with a top-to-bottom, F-shaped scanning pattern. Place primary actions on the bottom left, where users finish scanning. In left-aligned layouts, the primary button is the leftmost. In right-aligned layouts, it is the rightmost.
Do: Put the primary action in the leftmost position so the user's eye never has to leave the one side.
Don't: Put the actions far away from the content.
Button placement should always reflect the surrounding context. Place the primary action (e.g. Create) in the top-right corner near the page title when the view contains structured content. For empty states — where space is limited and the focus is on guiding the user — center-align both the title and the primary action.
Do: If the action is against the page title, place the primary button in the upper right.
Do: Center-align the title and primary action when content is minimal and vertically constrained.
Split buttons
EUI does not specifically support split buttons. Instead, use separate EuiButton and EuiButtonIcon components, matching their display and size props for consistency.
Popover buttons
Combine multiple actions into a single button with a popover menu to reduce group size.
Do: Put multiple actions inside a menu triggered by a single rather than showing them separately.
Don't: When there are many buttons, none matter.
Toggle button
Create toggle buttons with EuiButton, EuiButtonEmpty, or EuiButtonIcon using state management for visual changes.
If the button's readable text (children or aria-label) changes when toggling the button, no additional accessibility concern exists.
If only the visual appearance changes, add aria-pressed with a boolean for on/off states. All EUI button types provide an isSelected helper prop for this.
Accessibility
Do not add aria-pressed or isSelected if the readable text changes.
Save button
Save buttons are specific to CRUD operations. "Save" is recommended for permanently saving data, rather than "Update," "Create," or "Apply." Reserve "Apply" for temporary changes.
Do: Place the primary action on the bottom right with the secondary action on its left in modals.
Do: Always use buttons positioned to the right in popovers.
The save button should be the most dominant action, consistent across contexts. Use the fill property and primary color variant, including a noun in the label (e.g., "Save dashboard"). An icon for "Save" button typically is not needed. Save buttons should be visually dominant, making an icon less necessary compared to other actions. Rely solely on the label to avoid inconsistency. Exceptions exist, such as the EuiInlineEdit component, which offers a save action without a label.
Do: Save button is a clear dominant within a group of actions.
Don't: Even though there are only two buttons, 'Save' should still be the primary action.
Props
EuiButton
Prop | Description and type | Default value |
|---|---|---|
Prop href# | Description and type Type: string | Default value |
Prop element# | Description and type Type: "a" | "button" | "span" | Default value |
Prop size# | Description and type Use size "s" | "m" | Default value m |
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 isLoading# | Description and type Force disables the button and changes the icon to a loading spinner boolean | Default value |
Prop contentProps# | Description and type Object of props passed to the wrapping the button's content CommonProps & EuiButtonDisplayContentType | Default value |
Prop style# | Description and type Type: CSSProperties | Default value |
Prop type# | Description and type Type: "button" | "reset" | "submit" | 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 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 isDisabled# | Description and type
boolean | Default value |
Prop className# | Description and type Type: string | 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 css# | Description and type Type: Interpolation<Theme> | 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,
"primary" | "text" | "accent" | "accentSecondary" | "success" | "warning" | "danger" | "neutral" | "risk" | Default value primary |
Prop onClick# | Description and type Type: MouseEventHandler<HTMLAnchorElement> | MouseEventHandler<HTMLButtonElement> | Default value |
Prop buttonRef# | Description and type Type: Ref<HTMLAnchorElement> | Ref<HTMLButtonElement> | Default value |
EuiButtonEmpty
Prop | Description and type | Default value |
|---|---|---|
Prop color# | Description and type Any of the named color palette options. Do not use the following colors for standalone buttons directly,
"primary" | "text" | "accent" | "accentSecondary" | "success" | "warning" | "danger" | "neutral" | "risk" | Default value primary |
Prop size# | Description and type Type: "xs" | "s" | "m" | Default value m |
Prop flush# | Description and type Ensure the text of the button sits flush to the left, right, or both sides of its container "left" | "right" | "both" | Default value |
Prop isDisabled# | Description and type
boolean | Default value |
Prop isLoading# | Description and type Force disables the button and changes the icon to a loading spinner boolean | Default value |
Prop isSelected# | Description and type Applies the boolean state as the boolean | Default value |
Prop href# | Description and type Type: string | Default value |
Prop target# | Description and type Type: string | Default value |
Prop rel# | Description and type Type: string | Default value |
Prop type# | Description and type Type: "button" | "reset" | "submit" | Default value button |
Prop buttonRef# | Description and type Type: Ref<HTMLAnchorElement | HTMLButtonElement> | Default value |
Prop contentProps# | Description and type Object of props passed to the CommonProps & EuiButtonDisplayContentType | Default value |
Prop iconType# | Description and type Any IconType | Default value |
Prop iconSide# | Description and type Can only be one side ButtonContentIconSide | Default value left |
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 m |
Prop className# | Description and type Type: string | 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 css# | Description and type Type: Interpolation<Theme> | Default value |
Prop onClick# | Description and type Type: MouseEventHandler<HTMLAnchorElement> | MouseEventHandler<HTMLButtonElement> | Default value |
EuiButtonIcon
Prop | Description and type | Default value |
|---|---|---|
Prop iconType# | Description and type Type: IconType | Default value Required |
Prop href# | Description and type Type: string | Default value |
Prop type# | Description and type Type: string | Default value button |
Prop color# | Description and type Any of the named color palette options. Do not use the following colors for standalone buttons directly,
"primary" | "text" | "accent" | "accentSecondary" | "success" | "warning" | "danger" | "neutral" | "risk" | Default value primary |
Prop aria-label# | Description and type Defines a string value that labels the current element. string | Default value |
Prop aria-labelledby# | Description and type Identifies the element (or elements) that labels the current element. string | Default value |
Prop isDisabled# | Description and type Type: boolean | Default value |
Prop size# | Description and type Overall size of button. "xs" | "s" | "m" | Default value xs |
Prop iconSize# | Description and type Size of the icon only. "s" | "m" | "l" | "xl" | "xxl" | "original" | Default value m |
Prop isSelected# | Description and type Applies the boolean state as the boolean | Default value |
Prop display# | Description and type Sets the display style for matching other EuiButton types. "base" | "fill" | "empty" | Default value empty |
Prop isLoading# | Description and type Disables the button and changes the icon to a loading spinner boolean | Default value |
Prop className# | Description and type Type: string | Default value |
Prop data-test-subj# | Description and type Type: string | Default value |
Prop css# | Description and type Type: Interpolation<Theme> | Default value |
Prop onClick# | Description and type Type: MouseEventHandler<HTMLAnchorElement> | MouseEventHandler<HTMLButtonElement> | Default value |
Prop buttonRef# | Description and type Type: Ref<HTMLAnchorElement> | Ref<HTMLButtonElement> | Default value |