Select Since v4.1.0

Overview

Style

Guidelines

Code

Accessibility

Demos

Importing

Usage

Validation and error state

rh-select

rh-option-group

rh-option

Importing

Usage

Validation and error state

rh-select

rh-option-group

rh-option

Importing

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

<script type="module">
  import '@rhds/elements/rh-select/rh-select.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.

Lightdom CSS

This element requires you to load "Lightdom CSS" stylesheets for styling deeply slotted elements.

Note

Replace /path/to/ with path to the CSS file, whether local or CDN.

<link rel="stylesheet" href="/path/to/rh-select/rh-select-lightdom.css">

Lightdom CSS shim

Warning

Lightdom CSS shims are an optional, temporary solution for reducing CLS. Learn more about lightdom CSS shims .

<link rel="stylesheet" href="/path/to/rh-select/rh-select-lightdom-shim.css">

Note

Replace /path/to/ with path to the CSS file, whether local or CDN.

When users set the required property and the no option is selected, the component participates in the Constraint Validation API. It sets an internal validity state (valueMissing), so the browser can show "Please fill out this field" when the user submits the form or when you call reportValidity(). Use checkValidity() or reportValidity() on the <rh-select> element to validate before submit.

See the Required demo for an example of this functionality.

Custom validation and error state

This component does not set aria-invalid when setting state="danger". For custom errors, you should:

Visual state: Set state="danger" and help-text="My error message" with the error message.
Semantic state for assistive tech: Set aria-invalid="true" on the <rh-select> so screen readers announce the invalid state.
Blocking form submit: The component only sets validity for required with an empty value. For custom rules, handle submit yourself:
- In your submit handler, run your custom check.
- If the check fails: call preventDefault() so the form does not submit then set state="danger", help-text, and aria-invalid="true" so the user sees and hears the error.
- If the check passes: clear the error state and allow the form to submit.

Example: validate on submit and show a custom error state when the selected option fails a rule.

<form id="my-form">
  <label for="region">Region</label>
  <rh-select id="region" name="region" placeholder="Select a region">
    <rh-option value="us">United States</rh-option>
    <rh-option value="eu">European Union</rh-option>
    <rh-option value="deprecated">Legacy (deprecated)</rh-option>
  </rh-select>
  <button type="submit">Submit</button>
</form>

<script type="module">
  import '@rhds/elements/rh-select/rh-select.js';

  const form = document.getElementById('my-form');
  const select = document.getElementById('region');

  form.addEventListener('submit', (e) => {
    const value = select.value;
    if (value === 'deprecated') {
      e.preventDefault();
      select.setAttribute('state', 'danger');
      select.setAttribute('help-text', 'This option is no longer available.');
      select.setAttribute('aria-invalid', 'true');
      select.focus();
    } else {
      select.removeAttribute('state');
      select.setAttribute('help-text', '');
      select.removeAttribute('aria-invalid');
    }
  });
</script>

For accessibility implications and why the component does not set aria-invalid from state, see Validation and error state in the Select accessibility documentation.

rh-select

A select element allows users to Select from an expandable list.

Theming

Themable

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

Slots 3

Slot Name	Summary	Description
`placeholder`		Placeholder inline text for the select. Overrides the `placeholder` attribute. Screen readers announce this text as the default label when no other label is provided.
`[default]`		Insert `rh-option` elements and optional `rh-option-group` or `hr` separator elements. Each `rh-option` must have accessible text content (slotted text or `label` attribute) so screen readers can announce it. Note: [default] unnamed slots do not have a slot="name" attribute.
`help-text`		Insert a block element (e.g. `<p>`) with text that helps describe the select. Overrides the `help-text` attribute when slotted. Content is automatically linked to the control via `aria-describedby` so screen readers announce it.

Attributes 9

Attribute	DOM Property	Description	Type	Default
`accessible-label`	`accessibleLabel`	Accessible label text for screen readers and assistive technologies. Should be used when the select lacks an associated `<label>` element. Required for accessibility compliance when no visible label is present.	`string`	`unknown`
`disabled`	`disabled`	Whether the select control is disabled and non-interactive. When true, prevents user interaction and excludes the value from form submission.	`boolean`	`false`
`expanded`	`expanded`	Whether the dropdown listbox is currently expanded and visible. Automatically managed by keyboard and mouse interactions. Should not be manually set in most cases.	`boolean`	`false`
`required`	`required`	When true, the user must select an option with a non-empty value before the form can be submitted. Syncs to aria-required and constraint validation so the browser can show "Please fill out this field" when the value is empty.	`boolean`	`false`
`value`	`value`	Current form value representing the selected option's value attribute. Updates automatically when selection changes. Use for form submission and programmatic value access.	`string`	`unknown`
`name`	`name`	Form control name. Submitted with the form as the key for this control's value in FormData. Reflects to the name attribute.	`string`	`unknown`
`placeholder`	`placeholder`	Placeholder text displayed when no option is selected. Should provide guidance about expected input. Overridden by the placeholder slot if provided. Used as fallback accessible label when no accessible-label or associated label is present.	`string`	`unknown`
`help-text`	`helpText`	Help text displayed below the control. Content slotted into the help-text slot overrides this attribute.	`string`	`unknown`
`state`	`state`	Visual and semantic state of the form control for user feedback. Use 'danger' for blocking errors that prevent form submission, 'warning' for non-blocking issues requiring attention, and 'success' for valid selections. Affects styling.	`'danger' \| 'success' \| 'warning'`	`unknown`

Methods 5

Method Name	Description
`checkValidity()`	Returns true if the element's value passes constraint validation. Participates in the Constraint Validation API; updates validity state before checking.
`reportValidity()`	Returns true if the element's value passes constraint validation. If invalid, reports the problem (e.g. browser "Please fill out this field") and returns false. Participates in the Constraint Validation API.
`show()`	Opens the dropdown
`hide()`	Closes the dropdown
`toggle()`	Toggles the dropdown based on current state

Events 3

Event Name	Description
`open`	Fires when the dropdown listbox opens. Does not bubble. The event has no `detail` payload.
`close`	Fires when the dropdown listbox closes. Does not bubble. The event has no `detail` payload.
`change`	Fires when the selected value changes. Bubbles. The event has no `detail` payload; read the new value from the `value` property.

CSS Shadow Parts 0

None

CSS Custom Properties 4

CSS Property	Description	Default
`--rh-color-status-disabled`		`light-dark( var(--rh-color-gray-30, #c7c7c7), var(--rh-color-gray-40, #a3a3a3))`
`--rh-color-text-status-disabled`		`light-dark( var(--rh-color-gray-50, #707070), var(--rh-color-gray-60, #4d4d4d))`
`--rh-color-icon-status-disabled`		`light-dark( var(--rh-color-gray-40, #a3a3a3), var(--rh-color-gray-60, #4d4d4d))`
`--rh-select-icon-size`		`14px`

Design Tokens 26

Token	Description	Copy
`--rh-font-weight-body-text-regular`	Regular font weight design token Regular font weight	Full CSS Variable Permalink to this token
`--rh-line-height-body-text`	Body text line height design token Line height for body text	Full CSS Variable Permalink to this token
`--rh-box-shadow-sm`	Small shadow design token for dropdown elevation Small box shadow	Full CSS Variable Permalink to this token
`--rh-color-surface-lightest`	Primary surface (light theme)	Full CSS Variable Permalink to this token
`--rh-color-surface-darkest`	Primary surface (dark theme)	Full CSS Variable Permalink to this token
`--rh-border-radius-default`	Default border radius design token 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.	Full CSS Variable Permalink to this token
`--rh-color-gray-30`	Subtle borders (light scheme)	Full CSS Variable Permalink to this token
`--rh-color-text-primary`	Primary text color design token for the select control Primary text color for the toggle button label	Full CSS Variable Permalink to this token
`--rh-font-family-body-text`	Body text font family design token Body text font stack for the toggle button Body text font family	Full CSS Variable Permalink to this token
`--rh-space-lg`	16px spacer	Full CSS Variable Permalink to this token
`--rh-color-gray-50`	Subtle icon	Full CSS Variable Permalink to this token
`--rh-border-width-md`	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.	Full CSS Variable Permalink to this token
`--rh-color-border-interactive`		Full CSS Variable Permalink to this token
`--rh-color-gray-40`	Subtle icon (hover state)	Full CSS Variable Permalink to this token
`--rh-color-gray-60`	Secondary text (light scheme)	Full CSS Variable Permalink to this token
`--rh-border-width-sm`	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.	Full CSS Variable Permalink to this token
`--rh-color-border-subtle`		Full CSS Variable Permalink to this token
`--rh-space-md`	Medium spacing design token for vertical padding Medium spacing between toggle text and icons 8px spacer	Full CSS Variable Permalink to this token
`--rh-font-size-body-text-sm`	Small body text size design token Small body text size for the toggle button 14px font size	Full CSS Variable Permalink to this token
`--rh-font-weight-body-text-medium`	Medium font weight	Full CSS Variable Permalink to this token
`--rh-color-border-status-success`		Full CSS Variable Permalink to this token
`--rh-color-border-status-warning`		Full CSS Variable Permalink to this token
`--rh-color-border-status-danger`		Full CSS Variable Permalink to this token
`--rh-color-icon-status-success`		Full CSS Variable Permalink to this token
`--rh-color-icon-status-warning`		Full CSS Variable Permalink to this token
`--rh-color-icon-status-danger`		Full CSS Variable Permalink to this token

rh-option-group

Groups related rh-option elements within an rh-select for organizing options into categories. Provides visual separation when used with <hr>. Should include a label for screen readers (ARIA group role). When disabled, all child options are disabled. Arrow keys and Tab navigate through grouped options the same way as ungrouped options.

Theming

Themable

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

Slots 2

Slot Name	Summary	Description
`label`		Group label as inline text. Overrides the `label` attribute. Screen readers announce this text when the group receives focus.
`[default]`		Insert `<rh-option>` elements. Each option must have accessible text content for screen readers. Note: [default] unnamed slots do not have a slot="name" attribute.

Attributes 2

Attribute	DOM Property	Description	Type	Default
`label`	`label`	Group label text displayed above the option group for identification. Should be used to describe the category or purpose of grouped options. Overridden by the label slot if provided. Required for accessibility.	`string`	`unknown`
`disabled`	`disabled`	Whether the option group and all its child options are disabled. When true, automatically disables all rh-option children, preventing selection of any options within this group.	`boolean`	`false`

Methods 0

None

Events 0

None

CSS Shadow Parts 0

None

CSS Custom Properties 1

CSS Property	Description	Default
`--rh-color-text-status-disabled`		`—`

Design Tokens 6

Token	Description	Copy
`--rh-color-gray-50`	Subtle icon	Full CSS Variable Permalink to this token
`--rh-color-gray-60`	Secondary text (light scheme)	Full CSS Variable Permalink to this token
`--rh-color-text-secondary`	Secondary text color design token for the group label	Full CSS Variable Permalink to this token
`--rh-font-size-body-text-xs`	Extra-small text size design token for the group label 12px font size	Full CSS Variable Permalink to this token
`--rh-space-md`	Medium spacing design token for vertical padding 8px spacer	Full CSS Variable Permalink to this token
`--rh-space-lg`	16px spacer	Full CSS Variable Permalink to this token

rh-option

An option within an rh-select dropdown. Must be a child of rh-select or rh-option-group. Should include a value attribute for form data. Must have text content or label for screen readers (ARIA option role). Press Enter/Space to select; Arrow keys to navigate between options.

Theming

Themable

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

Slots 2

Slot Name	Summary	Description
`[default]`		Option label as inline text. Screen readers use this content as the accessible name. Falls back to the `label` or `value` attribute when empty. Note: [default] unnamed slots do not have a slot="name" attribute.
`description`		Optional inline or block description text displayed below the option label. Overrides the `description` attribute. Should be a `<span>` or `<p>` element.

Attributes 7

Attribute	DOM Property	Description	Type	Default
`disabled`	`disabled`	Whether the option is disabled and cannot be selected. Defaults to `false`.	`boolean`	`false`
`value`	`value`	Form value for this option. Priority: value attr -> displayLabel -> ''	`unknown`	`unknown`
`selected`	`selected`	Whether the option is currently selected. Defaults to `false`.	`boolean`	`false`
`icon-set`	`iconSet`	Icon set for the optional rh-icon to precede the option text - 'ui' by default	`'ui' \| 'standard' \| 'social' \| 'microns'`	`'ui'`
`icon`	`icon`	The icon name of an rh-icon	`IconNameFor<IconSetName>`	`unknown`
`description`	`description`	Optional option description; overridden by description slot.	`string`	`unknown`
`label`	`label`	Display text for this option; overridden by slotted text content	`string`	`unknown`

CSS Property	Description	Default
`--rh-color-text-status-disabled`		`light-dark( var(--rh-color-gray-50, #707070), var(--rh-color-gray-60, #4d4d4d))`
`--rh-select-icon-size`		`14px`

Design Tokens 11

Token	Description	Copy
`--rh-color-surface-lighter`	Tertiary surface (light theme)	Full CSS Variable Permalink to this token
`--rh-color-surface-darker`	Secondary surface (dark theme)	Full CSS Variable Permalink to this token
`--rh-space-lg`	16px spacer	Full CSS Variable Permalink to this token
`--rh-border-radius-default`	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.	Full CSS Variable Permalink to this token
`--rh-color-border-interactive`		Full CSS Variable Permalink to this token
`--rh-border-width-lg`	Applies a 3px border width to 1 side of a container. It should be used for strong directional emphasis like indicating a current page, expanded, or selected state. Recommended for elements needing heavy visual weight like Accordion, Navigation, or Tabs. It must also be used for the focus indicator border per WCAG. Except for the focus indicator, it should not be applied to all 4 sides at once.	Full CSS Variable Permalink to this token
`--rh-color-gray-50`	Subtle icon	Full CSS Variable Permalink to this token
`--rh-color-gray-60`	Secondary text (light scheme)	Full CSS Variable Permalink to this token
`--rh-color-interactive-primary-default`	Primary interactive color design token for selected checkmark	Full CSS Variable Permalink to this token
`--rh-font-size-body-text-xs`	Extra-small text size design token for option descriptions 12px font size	Full CSS Variable Permalink to this token
`--rh-space-md`	Medium spacing design token between icon and label 8px spacer	Full CSS Variable Permalink to this token

Edit this page on GitHub

Note

Warning

Note

Other libraries

Feedback

Related elements or patterns

Red Hat footer

Red Hat legal and privacy links

Red Hat legal and privacy links