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 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 Scheme toggle Site status Skeleton Skip link Spinner Statistic Subnavigation Surface Switch Table Tabs Tag Tile Timestamp Tooltip Video embed OverviewColor PalettesCustomizingDevelopers All PatternsAccordionCall to ActionCardFilterFormLink with iconLogo wallSearch barSticky bannerSticky cardTabsTagTile All Personalization PatternsAnnouncement FundamentalsAccessibility toolsAssistive technologiesCI/CDContentContributorsDesignDevelopmentManual testingResourcesScreen readers Design/code status Release notes Get support

Button

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 

<meta itemprop="description" content="Default primary button demonstrating base button usage and styling.">
<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. MUST use label for icon-only buttons to set the ARIA accessible name. Supports form association (submit/reset).

Slots 2

Slot Name Summary Description
icon

icon slot for visual indicators

Contains the button's icon or state indicator (e.g. spinner). 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

Text content displayed inside the button. Hidden from screen readers via aria-hidden when the label attribute is set. For close and play variants, text is visually hidden but remains accessible. SHOULD provide concise, action-oriented text (e.g. "Submit", "Delete").
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
label label

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

Contains the button's icon or state indicator (e.g. spinner). Wrapped in aria-hidden span so screen readers skip decorative icons. Close and play variants auto-populate this slot via #renderIcon().

CSS Custom Properties 2

CSS Property Description Default
--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-border-radius-default

Button corner radius; uses --rh-border-radius-default design token

Button corner rounding

3px border radius; Example: Card
--rh-space-sm

Button vertical spacing

Button content gap

6px spacer
--rh-space-lg

Button horizontal spacing

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

Primary interactive - hover (Light theme)
--rh-color-interactive-primary-hover
--rh-color-text-primary-on-dark

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

Primary text color for light theme
--rh-color-status-danger
--rh-color-border-status-danger
--rh-color-red-60

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

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

1px border width; Example: Secondary CTA or Button
--rh-color-text-primary
--rh-color-border-strong
--rh-border-width-md

2px border width: Example: Alert
--rh-color-blue-70

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

Primary interactive - hover (Dark theme)
--rh-color-icon-secondary
--rh-color-interactive-secondary-active
--rh-color-interactive-secondary-focus
--rh-color-interactive-secondary-hover
--rh-length-lg

Button width

16px length token
--rh-opacity-50

50% opacity
--rh-color-interactive-primary-default
--rh-color-gray-90

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

80% opacity
--rh-length-4xl

Button width

64px length token
--rh-color-icon-secondary-on-dark
--rh-color-icon-secondary-on-light
--rh-color-gray-50

Subtle icon
--rh-color-gray-60

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

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

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