Skip to content
PatternFly.org Contribute on Github
PatternFly Elements

Select

A select list enables users to select one or more items from a list.

A select component consists of a toggle control to open and close a menu of actions or links. Selects differ from dropdowns in that they persist selection, whereas dropdowns are typically used to present a list of actions or links.

Installation

We recommend loading elements via a CDN such as JSPM and using an import map to manage your dependencies.

For more information on import maps and how to use them, see the import map reference on MDN Web Docs.

If you are using node and NPM, you can install this component using npm:

npm install @patternfly/elements

Then import this component into your project by using a bare module specifier:

import '@patternfly/elements/pf-select/pf-select.js';

Please Note You should either load elements via a CDN or install them locally through NPM. Do not do both.

Overview

Blue Green Magenta Orange Purple Pink Red Yellow

Installation

npm install @patternfly/elements

Usage

Single

Focus on options using arrow keys or by typing the first character of an option.

Blue Green Magenta Orange Purple Pink Red Yellow
View HTML Source 
<pf-select default-text="Select a value">
  <pf-option value="Blue">Blue</pf-option>
  <pf-option value="Green">Green</pf-option>
  <pf-option value="Magenta">Magenta</pf-option>
  <pf-option value="Orange">Orange</pf-option>
  <pf-option value="Purple">Purple</pf-option>
  <pf-option value="Pink">Pink</pf-option>
  <pf-option value="Red">Red</pf-option>
  <pf-option value="Yellow">Yellow</pf-option>
</pf-select>

Disabled

Blue Green Magenta Orange Purple Pink Red Yellow
View HTML Source 
<pf-select disabled default-text="Select a color">
  <pf-option value="Blue">Blue</pf-option>
  <pf-option value="Green">Green</pf-option>
  <pf-option value="Magenta">Magenta</pf-option>
  <pf-option value="Orange">Orange</pf-option>
  <pf-option value="Purple">Purple</pf-option>
  <pf-option value="Pink">Pink</pf-option>
  <pf-option value="Red">Red</pf-option>
  <pf-option value="Yellow">Yellow</pf-option>
</pf-select>

Option variations

Below are option variants:

Basic option Option with description This is a description Option with icon Aria-disabled option
View HTML Source 
<pf-select always-expanded>
  <pf-option value="Basic">Basic option</pf-option>
  <pf-option value="Description">
    <span>Option with description</span>
    <span slot="description">This is a description</span>
  </pf-option>
  <pf-option value="Icon">
    <pf-icon size="md" icon="paint-brush" set="fas" slot="icon"></pf-icon>
    Option with icon
  </pf-option>
  <pf-option value="aria-disabled" aria-disabled="true">Aria-disabled option</pf-option>
</pf-select>

Note: WAI-ARIA recommends elements of a larger composite widget remain focusable.

Because options are part of the larger `pf-select` element, use `aria-disabled="true"` instead of `disabled` so that screenreader users know the option exists and is disabled.

Grouped Options

Breakfast Eggs Toast Waffles Lunch Salad Sandwich Soup
View HTML Source 
<pf-select default-text="Select item from our menu">
  <pf-option-group>
    <span slot="label">Breakfast</span>
    <pf-option value="Eggs">Eggs</pf-option>
    <pf-option value="Toast">Toast</pf-option>
    <pf-option value="Waffles">Waffles</pf-option>
  </pf-option-group>
  <pf-option-group>
    <span slot="label">Lunch</span>
    <pf-option value="Salad">Salad</pf-option>
    <pf-option value="Sandwich">Sandwich</pf-option>
    <pf-option value="Soup">Soup</pf-option>
  </pf-option-group>
</pf-select>

Multi-selectable

Multiple options can be selected. Any arrow keys work. Shift will toggling off multiple items. Ctrl+A will toggle selection on all items.

Blue Green Magenta Orange Purple Pink Red Yellow
View HTML Source 
<pf-select multi>
  <pf-option value="Blue">Blue</pf-option>
  <pf-option value="Green">Green</pf-option>
  <pf-option value="Magenta">Magenta</pf-option>
  <pf-option value="Orange">Orange</pf-option>
  <pf-option value="Purple">Purple</pf-option>
  <pf-option value="Pink">Pink</pf-option>
  <pf-option value="Red">Red</pf-option>
  <pf-option value="Yellow">Yellow</pf-option>
</pf-select>

Checkbox

Multiple options, displayed as checkboxes, can be selected. Shift will toggling off multiple items. Ctrl+A will toggle selection on all items.

Blue Green Magenta Orange Purple Pink Red Yellow
View HTML Source 
<pf-select checkboxes>
  <pf-option value="Blue">Blue</pf-option>
  <pf-option value="Green">Green</pf-option>
  <pf-option value="Magenta">Magenta</pf-option>
  <pf-option value="Orange">Orange</pf-option>
  <pf-option value="Purple">Purple</pf-option>
  <pf-option value="Pink">Pink</pf-option>
  <pf-option value="Red">Red</pf-option>
  <pf-option value="Yellow">Yellow</pf-option>
</pf-select>

Checkbox, with badge

Blue Green Magenta Orange Purple Pink Red Yellow
View HTML Source 
<pf-select checkboxes selected-items-display="badge">
  <pf-option value="Blue">Blue</pf-option>
  <pf-option value="Green">Green</pf-option>
  <pf-option value="Magenta">Magenta</pf-option>
  <pf-option value="Orange">Orange</pf-option>
  <pf-option value="Purple">Purple</pf-option>
  <pf-option value="Pink">Pink</pf-option>
  <pf-option value="Red">Red</pf-option>
  <pf-option value="Yellow">Yellow</pf-option>
</pf-select>

Typeahead

View HTML Source 
<label>
  Pick a color:
  <pf-select typeahead>
    <pf-option value="Blue">Blue</pf-option>
    <pf-option value="Green">Green</pf-option>
    <pf-option value="Magenta">Magenta</pf-option>
    <pf-option value="Orange">Orange</pf-option>
    <pf-option value="Purple">Purple</pf-option>
    <pf-option value="Pink">Pink</pf-option>
    <pf-option value="Red">Red</pf-option>
    <pf-option value="Yellow">Yellow</pf-option>
  </pf-select>
</label>

Typeahead with create option

View HTML Source 

<label>
  Pick a color:
  <pf-select id="pfselect" typeahead create-option-text="Create option">
    <pf-option value="Blue">Blue</pf-option>
    <pf-option value="Green">Green</pf-option>
    <pf-option value="Magenta">Magenta</pf-option>
    <pf-option value="Orange">Orange</pf-option>
    <pf-option value="Purple">Purple</pf-option>
    <pf-option value="Pink">Pink</pf-option>
    <pf-option value="Red">Red</pf-option>
    <pf-option value="Yellow">Yellow</pf-option>
  </pf-select>
</label>

Typeahead, multi with chips

View HTML Source 

<label>
  Pick a color:
  <pf-select typeahead multi selected-items-display="chips">
    <pf-option value="Blue">Blue</pf-option>
    <pf-option value="Green">Green</pf-option>
    <pf-option value="Magenta">Magenta</pf-option>
    <pf-option value="Orange">Orange</pf-option>
    <pf-option value="Purple">Purple</pf-option>
    <pf-option value="Pink">Pink</pf-option>
    <pf-option value="Red">Red</pf-option>
    <pf-option value="Yellow">Yellow</pf-option>
  </pf-select>
</label>

Typeahead, multi with create option

View HTML Source 

<label>
  Pick a color:
  <pf-select id="pfselect" typeahead multi create-option-text="Create option">
    <pf-option value="Blue">Blue</pf-option>
    <pf-option value="Green">Green</pf-option>
    <pf-option value="Magenta">Magenta</pf-option>
    <pf-option value="Orange">Orange</pf-option>
    <pf-option value="Purple">Purple</pf-option>
    <pf-option value="Pink">Pink</pf-option>
    <pf-option value="Red">Red</pf-option>
    <pf-option value="Yellow">Yellow</pf-option>
  </pf-select>
</label>

Typeahead, with checkboxes

View HTML Source 

<label>
  Pick a color:
  <pf-select id="pfselect" typeahead checkboxes>
    <pf-option value="Blue">Blue</pf-option>
    <pf-option value="Green">Green</pf-option>
    <pf-option value="Magenta">Magenta</pf-option>
    <pf-option value="Orange">Orange</pf-option>
    <pf-option value="Purple">Purple</pf-option>
    <pf-option value="Pink">Pink</pf-option>
    <pf-option value="Red">Red</pf-option>
    <pf-option value="Yellow">Yellow</pf-option>
  </pf-select>
</label>

Filtering

By default, filtering is enabled and not case sensitive. However, filtering can be set to case sensitive or disabled altogether.

Case-sensitive filtering

Blue Green Magenta Orange Purple Pink Red Yellow
View HTML Source 
<pf-select case-sensitive typeahead>
  <pf-option value="Blue">Blue</pf-option>
  <pf-option value="Green">Green</pf-option>
  <pf-option value="Magenta">Magenta</pf-option>
  <pf-option value="Orange">Orange</pf-option>
  <pf-option value="Purple">Purple</pf-option>
  <pf-option value="Pink">Pink</pf-option>
  <pf-option value="Red">Red</pf-option>
  <pf-option value="Yellow">Yellow</pf-option>
</pf-select>

Match anywhere

Filter options that match input text anywhere rather than just options that start with the input text.

Blue Green Magenta Orange Purple Pink Red Yellow
View HTML Source 
<pf-select match-anywhere typeahead>
  <pf-option value="Blue">Blue</pf-option>
  <pf-option value="Green">Green</pf-option>
  <pf-option value="Magenta">Magenta</pf-option>
  <pf-option value="Orange">Orange</pf-option>
  <pf-option value="Purple">Purple</pf-option>
  <pf-option value="Pink">Pink</pf-option>
  <pf-option value="Red">Red</pf-option>
  <pf-option value="Yellow">Yellow</pf-option>
</pf-select>

Disable filtering

Blue Green Magenta Orange Purple Pink Red Yellow
View HTML Source 
<pf-select disable-filter typeahead>
  <pf-option value="Blue">Blue</pf-option>
  <pf-option value="Green">Green</pf-option>
  <pf-option value="Magenta">Magenta</pf-option>
  <pf-option value="Orange">Orange</pf-option>
  <pf-option value="Purple">Purple</pf-option>
  <pf-option value="Pink">Pink</pf-option>
  <pf-option value="Red">Red</pf-option>
  <pf-option value="Yellow">Yellow</pf-option>
</pf-select>

Accessibility

The select uses the Combobox Pattern recommendations from the WAI ARIA Authoring Best Practices Guide (APG).

When the dropdown is disabled it follows WAI ARIA focusability recommendations for composite widget elements, where dropdown items are still focusable even when the dropdown is disabled.

Toggle button and typeahead input

When focus is on the toggle button, the following keyboard interactions apply:

Key Function
Enter Opens the listbox.
Space Opens the listbox.
Down Arrow Opens the listbox and moves focus to the first listbox item.
Tab Moves focus out of select element onto the next focusable item and closes listbox.
Shift + Tab Moves focus out of select element onto the previous focusable item and closes listbox.

Listbox options

Listbox options use the APG's Roving tabindex recommendation. When focus is on the listbox, the following keyboard interactions apply:

Key Function
Enter Selects the options and closes the listbox.
Space Selects the options and closes the listbox.
Shift Enables multiselect.
Control + A Selects all options.
Tab Moves focus out of select element onto the next focusable options and closes listbox.
Shift + Tab Moves focus to the toggle button and closes listbox.
Up Arrow Moves focus to the previous option, optionally wrapping from the first to the last.
Down Arrow Moves focus to the next option, optionally wrapping from the last to the first.
Left Arrow Moves focus to the previous option, optionally wrapping from the first to the last.
Right Arrow Moves focus to the next option, optionally wrapping from the last to the first.
Home Moves focus to the first option in the current listbox.
End Moves focus to the last option in the current listbox.
Escape Close the listbox that contains focus and return focus to the toggle button.
Any letter Navigates to the next option that starts with the letter.

Slots on pf-select

Default Slot

insert pf-option and/or pf-option-groups here

Attributes on pf-select

accessible-label

Accessible label for chip group that does not have a category name

DOM Property
accessibleLabel
Type
string
Default
''
always-expanded

whether listbox is always expanded

DOM Property
alwaysExpanded
Type
boolean
Default
false
case-sensitive

whether filtering (if enabled) will be case-sensitive

DOM Property
caseSensitive
Type
boolean
Default
false
checkboxes

whether listbox is has checkboxes when multi-select is enabled

DOM Property
checkboxes
Type
boolean
Default
false
create-option-text

text for a special option that allows user to create an option from typeahead input text; set to '' in order to disable this feature

DOM Property
createOptionText
Type
string
Default
''
current-selections-label

Accessible label for chip group used to describe chips

DOM Property
currentSelectionsLabel
Type
string
Default
'Current selections'
default-text

listbox button text when single-select listbox has no selected option text

DOM Property
defaultText
Type
string
Default
'Options'
disabled

whether select is disabled

DOM Property
disabled
Type
boolean
Default
false
enable-flip

enable to flip listbox when it reaches boundary

DOM Property
enableFlip
Type
boolean
Default
false
filter

listbox filter

DOM Property
filter
Type
string
Default
''
items-selected-text

multi listbox button text

DOM Property
itemsSelectedText
Type
string
Default
'items selected'
match-anywhere

whether filtering (if enabled) will look for filter match anywhere in option text (by default it will only match if option starts with filter)

DOM Property
matchAnywhere
Type
boolean
Default
false
multi

whether multiple items can be selected

DOM Property
multi
Type
boolean
Default
false
position

Indicates initial popover position. There are 6 options: bottom, top, top-start, top-end, bottom-start, bottom-end. Default is bottom.

DOM Property
position
Type
Placement
Default
'bottom'
selected-items-display

how listbox will display multiple items in toggle area: 'badge' for a badge with item count, 'chips' for a group of chips, '' for # items selected text (default)

DOM Property
selectedItemsDisplay
Type
'default' | 'badge' | 'chips'
Default
'default'
typeahead

whether listbox controlled by combobox that supports typing

DOM Property
typeahead
Type
boolean
Default
false
expanded

Whether the select listbox is expanded

DOM Property
expanded
Type
unknown
Default
unknown

Methods on pf-select

show()

Opens the dropdown

insertOption(option: PfOption, insertBefore: PfOption)

Allows new options to be inserted

hide()

Closes listbox and sets focus

Events on pf-select

open

when the menu toggles open

Event Type: 
unknown
close

when the menu toggles closed

Event Type: 
unknown

CSS Custom Properties on pf-select

None

CSS Parts on pf-select

None

Slots on pf-option-group

Default Slot

Place element content here

Attributes on pf-option-group

disabled

whether group is disabled

DOM Property
disabled
Type
boolean
Default
false

Methods on pf-option-group

None

Events on pf-option-group

None

CSS Custom Properties on pf-option-group

None

CSS Parts on pf-option-group

None

Slots on pf-option

Default Slot

option text

icon

optional icon

description

optional description

Attributes on pf-option

disabled

whether option is disabled

DOM Property
disabled
Type
boolean
Default
false
value

form value for this option

DOM Property
value
Type
string
Default
''
selected

whether option is selected

DOM Property
selected
Type
boolean
Default
false
active

whether option is active descendant

DOM Property
active
Type
boolean
Default
false
description

Optional option description; overridden by description slot.

DOM Property
description
Type
string
Default
''

Methods on pf-option

None

Events on pf-option

select

Fired on option select/deselect

Event Type: 
PfOptionSelectEvent
focus

Fired on option focus

Event Type: 
PfOptionFocusEvent
blur

Fired on option blur

Event Type: 
PfOptionBlurEvent

CSS Custom Properties on pf-option

None

CSS Parts on pf-option

None

© 2018-2024 Red Hat, Inc. Deploys by Netlify