Skip to main content Home About the Design SystemRoadmap OverviewDesignersDevelopers OverviewColorGridIconographyInteractionsSpacingTypography Overview Global colorBox shadowTypographyBorderOpacitySpaceLengthIconBreakpointsMedia queries All elements Accordion Alert Announcement Audio player Avatar Back to top Badge Blockquote Breadcrumb Button group Button Card Chip Code block Call to action Dialog Disclosure Footer Health index Icon Jump links Menu dropdown Navigation link Navigation (primary) Navigation (secondary) Navigation (vertical) Pagination PopoverPlanned Progress stepper Readtime Scheme dropdown Scheme toggle Select Site status Skeleton Skip link Spinner Statistic Subnavigation Surface Switch Table Tabs Tag Tile Timestamp Tooltip Video embed How to useProject FeltColor PalettesCustomizingDevelopers All PatternsAccordionAlertCall to ActionCardFilterFormLink with iconLogo wallSearch barSticky bannerSticky cardTabsTagTile AI design principlesLegal requirementsTransparency noticesIconographyColorChatbot avatarsAnimation All Personalization PatternsAnnouncement FundamentalsAccessibility toolsAssistive technologiesCI/CDContentContributorsDesignDevelopmentManual testingResourcesScreen readers Design/code status Release notes Get support

Button Since v1.0.0

OverviewStyleGuidelinesCodeAccessibilityDemos
ImportingUsagerh-buttonUsage guidelinesAccessibilityImportingUsagerh-buttonUsage guidelinesAccessibility

Importing

Add rh-button to your page with this import statement:

<script type="module">
  import '@rhds/elements/rh-button/rh-button.js';
</script>
Copy to Clipboard Wrap lines

To learn more about installing RHDS elements on your site using an import map read our getting started docs.

Usage 

<rh-button>Primary</rh-button>

<script type="module">
  import '@rhds/elements/rh-button/rh-button.js';
</script>
Copy to Clipboard Wrap lines

rh-button

Triggers actions via click, Enter, or Space. USE variant to set hierarchy: primary (should limit one per page), secondary, tertiary, or danger. Renders a native <button> with delegatesFocus for keyboard access. Icon-only buttons must set accessible-label to provide an ARIA accessible name. Supports form association (submit/reset).

Theming

Themable

This element uses Red Hat design system theming and can be used in themable contexts.

Slots 2

Slot Name Summary Description
icon

icon slot for visual indicators

Expects an rh-icon element or inline svg. Wrapped in aria-hidden span so screen readers skip decorative icons. Close and play variants auto-populate this slot via #renderIcon().
[default]

button text label

Expects inline text providing a concise, action-oriented label (e.g. "Submit", "Delete"). Hidden from screen readers via aria-hidden when accessible-label is set. For close and play variants, text is visually hidden but remains accessible.
Note: [default] unnamed slots do not have a slot="name" attribute.

Attributes 9

Attribute DOM Property Description Type Default
disabled disabled

Disables the button, preventing user interaction. When true, the button receives aria-disabled="true" and pointer events are suppressed. Disabled buttons are excluded from tab order unless aria-disabled is used instead of disabled. Defaults to false.

 
boolean
 
false
type type

Controls the button's behavior within a form context. Accepts 'button' (no default form behavior), 'submit' (submits the form), or 'reset' (resets form fields). When omitted, defaults to implicit submit behavior.

 
'button' | 'submit' | 'reset'
 
unknown
accessible-label accessibleLabel

Accessible name for the button, applied as aria-label on the internal <button>. Use when the button has no visible text (e.g. icon-only buttons like close or play). When set, slotted text is hidden with aria-hidden="true". Defaults to undefined.

 
string
 
unknown
value value

Form value submitted with the button when it triggers form submission. Paired with name to create a name/value pair. Defaults to undefined.

 
string
 
unknown
name name

Form name for the button, used with value to submit data when the button triggers form submission. Defaults to undefined.

 
string
 
unknown
icon icon

Shorthand for the icon slot. Accepts an icon name from the specified icon set (defaults to 'ui'). When set, renders an <rh-icon> in the icon slot. Should use micron icons for best fit. Defaults to undefined.

 
IconNameFor<IconSetName>
 
unknown
icon-set iconSet

Icon set for the icon property. Accepts any registered icon set name. Defaults to 'ui' when not specified. USE 'microns' for small inline icons.

 
'ui' | 'standard' | 'social' | 'microns'
 
unknown
variant variant

Controls the visual hierarchy and style of the button. Accepts 'primary' | 'secondary' | 'tertiary' | 'close' | 'play'. Defaults to 'primary'. Should limit primary to one per page. USE secondary for general actions, tertiary for low-emphasis actions. Close and play variants render icon-only circular buttons with visually hidden text.

 
'primary' | 'secondary' | 'tertiary' | 'close' | 'play'
 
'primary'
danger danger

Applies danger styling for destructive or irreversible actions like deleting data. Combines with variant to produce danger-primary or danger-secondary styles. AVOID using for non-destructive actions. Defaults to false.

 
boolean
 
false

Methods 1

Method Name Description
focus()

Programmatically moves focus to the button element.

This method focuses the internal button element, making it the active element on the page. Useful for managing focus flow after dynamic content changes or user interactions.

Usage guidelines

  • Use to direct user attention after completing an action
  • Helpful for accessibility when managing focus programmatically
  • Called automatically when the button is the target of a focus navigation
  • Can be used after modals close to return focus to a trigger button

Accessibility

  • When focus is moved programmatically, ensure users are aware of the change
  • Avoid moving focus unexpectedly as it can disorient users
  • Moving focus to a button should be deliberate and serve user needs
const button = document.querySelector('rh-button');
button.focus();

Events 0

None

CSS Shadow Parts 2

Part Name Summary Description
button

internal button element

Native button element that receives focus via delegatesFocus. Screen readers announce this as a button with the label or slotted text.
icon

icon slot for visual indicators

Expects an rh-icon element or inline svg. Wrapped in aria-hidden span so screen readers skip decorative icons. Close and play variants auto-populate this slot via #renderIcon().

CSS Custom Properties 8

CSS Property Description Default
--rh-button-icon-color

Set on the rh-button host to give the icon a distinct color from the button text.

 currentcolor
--rh-button-close-active-background transparent
--rh-button-close-focus-background transparent
--rh-button-close-hover-background transparent
--rh-button-close-width

Close button width

 var(--rh-length-lg, 16px)
--rh-button-close-radius

Close button radius

 var(--rh-border-radius-default, 3px)
--rh-color-text-status-disabled —
--rh-color-status-disabled —

Design Tokens 37

Token Description Copy
--rh-font-size-body-text-md

Button text size

16px font size
--rh-font-weight-body-text-regular

Button font weight

Regular font weight
--rh-line-height-body-text

Button line height

Line height for body text
--rh-length-4xs

Button focus ring offset

1px length token
--rh-space-sm

Button vertical spacing

Button content gap

6px spacer
--rh-space-lg

Button horizontal spacing

Button start spacing

16px spacer
--rh-color-interactive-primary-hover-on-light

Primary active background color

Primary focus background color

Primary interactive - hover (Light theme)
--rh-color-interactive-primary-hover

Primary hover background color
--rh-color-text-primary-on-dark

Primary text color for light scheme

Primary active text color

Primary focus text color

Primary hover text color for light scheme

Danger text color for light scheme

Danger active text color for light scheme

Danger focus text color for light scheme

Danger hover text color for light scheme

Primary text color for dark theme
--rh-color-text-primary-on-light

Primary text color for dark scheme

Primary hover text color for dark scheme

Danger text color for dark scheme

Danger active text color for dark scheme

Danger focus text color for dark scheme

Danger hover text color for dark scheme

Primary text color for light theme
--rh-color-status-danger

Danger background color

Secondary danger text color
--rh-color-border-status-danger

Secondary danger border color
--rh-color-red-60

Secondary danger focus text color for light scheme

Dark brand red
--rh-color-red-30

Secondary danger focus text color for dark scheme

Lighter brand red
--rh-border-width-sm

Primary border width

Primary active border width

Primary hover border width

Danger border width

Secondary border width

Tertiary border width

Applies a 1px border width to at least 1 side of a container. This shall be the default width for all borders and lines. It should be used to establish baseline thickness or visual separation with a container or thin line. It must not be used for strong directional emphasis like indicating a selected state. Recommended for elements like Button, Card, or Field. Applying to all 4 sides at once is optional.
--rh-color-text-primary

Tertiary text color

Tertiary active text color

Tertiary focus text color

Tertiary hover text color
--rh-color-border-strong

Tertiary border color

Tertiary active border color

Tertiary focus border color

Tertiary hover border color
--rh-color-blue-70

Link active text color for light scheme

Link focus text color for light scheme

Link hover text color for light scheme

Alert - Info title text
--rh-color-interactive-primary-hover-on-dark

Link active text color for dark scheme

Link focus text color for dark scheme

Link hover text color for dark scheme

Primary interactive - hover (Dark theme)
--rh-color-icon-secondary

Close icon color
--rh-color-interactive-secondary-active

Close active icon color
--rh-color-interactive-secondary-focus

Close focus icon color
--rh-color-interactive-secondary-hover

Close hover icon color
--rh-length-lg

16px length token
--rh-border-radius-default

Button corner radius

Button corner rounding

Applies a 3px border radius to at least 1 corner of a container. This shall be the default for all containers needing rounded corners. It should be used to soften a container's visual footprint. Recommended for elements with subtle rounded corners like Button, Card, or Dialog. It must be applied to all 4 corners of a container at once.
--rh-opacity-50

50% opacity
--rh-color-gray-90

Secondary surface (dark scheme)
--rh-opacity-80

80% opacity
--rh-length-4xl

Button width

64px length token
--rh-color-icon-secondary-on-dark

Play icon color

Play icon color for light scheme
--rh-color-icon-secondary-on-light

Play icon color for dark scheme
--rh-color-interactive-primary-default

Primary background color

Secondary text color

Secondary border color

Secondary active text color

Secondary active border color

Secondary focus text color

Secondary focus border color

Secondary hover text color

Secondary hover border color

Link text color

Link focus outline color

Close focus outline color

Play focus outline color

Focus outline color
--rh-border-width-md

Primary focus border width

Danger focus border width

Secondary active border width

Secondary focus border width

Secondary hover border width

Tertiary active border width

Tertiary focus border width

Tertiary hover border width

Focus outline width

Focus pseudo-element border width fallback

Applies a 2px border width to at least 1 side of a container. It should be used to add emphasis or visual separation beyond a 1px border. Recommended for elements needing extra thickness like Alert or Progress stepper. It must be used to ensure hover, focus, and active states are discernible by more than color alone per WCAG. Applying to all 4 sides at once is optional.
--rh-color-gray-50

Disabled text color for light scheme

Subtle icon
--rh-color-gray-60

Disabled text color for dark scheme

Secondary text (light scheme)
--rh-color-gray-30

Disabled background color for light scheme

Subtle borders (light scheme)
--rh-color-gray-40

Disabled background color for dark scheme

Subtle icon (hover state)
Edit this page on GitHub
© 2026 Red Hat Deploys by Netlify