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/elementsThen 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
Installation
npm install @patternfly/elementsUsage
Single
Focus on options using arrow keys or by typing the first character of an option.
View HTML Source
<pf-select placeholder="Select a title"
accessible-label="Title">
<pf-option>Mr</pf-option>
<pf-option>Miss</pf-option>
<pf-option>Mrs</pf-option>
<pf-option>Ms</pf-option>
<hr>
<pf-option>Dr</pf-option>
<pf-option>Other</pf-option>
</pf-select>
<script type="module">
import '@patternfly/elements/pf-select/pf-select.js';
</script>
Single with description
View HTML Source
<pf-select accessible-label="Title">
<pf-option description="This is a description">Mr</pf-option>
<pf-option description="This is a description">Miss</pf-option>
<pf-option description="This is a description">Mrs</pf-option>
<pf-option description="This is a description">Ms</pf-option>
<pf-option>Dr
<span slot="description">Descriptions can <em>also</em> be HTML</span>
</pf-option>
<pf-option description="This is a description">Other</pf-option>
</pf-select>
<script type="module">
import '@patternfly/elements/pf-select/pf-select.js';
</script>
Grouped single
View HTML Source
<pf-select accessible-label="Status">
<pf-option-group label="Status" key="group1">
<pf-option value="0">Running</pf-option>
<pf-option value="1">Stopped</pf-option>
<pf-option value="2">Down</pf-option>
<pf-option value="3">Degraded</pf-option>
<pf-option value="4">Needs maintenance</pf-option>
</pf-option-group>
<hr>
<pf-option-group label="Vendor names" key="group2">
<pf-option value="5">Dell</pf-option>
<pf-option value="6" disabled>Samsung</pf-option>
<pf-option value="7">Hewlett-Packard</pf-option>
</pf-option-group>
</pf-select>
<script type="module">
import '@patternfly/elements/pf-select/pf-select.js';
</script>
Checkbox input
Multiple options can be selected. Any arrow keys work. Shift will toggling off multiple items. Ctrl+A will toggle selection on all items.
View HTML Source
<pf-select variant="checkbox"
accessible-label="Status"
placeholder="Filter by status">
<pf-option description="This is a description">Active</pf-option>
<pf-option>Cancelled</pf-option>
<pf-option>Paused</pf-option>
<hr>
<pf-option>Warning</pf-option>
<pf-option>Restarted</pf-option>
</pf-select>
<script type="module">
import '@patternfly/elements/pf-select/pf-select.js';
</script>
When setting the disabled attribute on options, they are still focusable, but
they are not selectable. This is in order that they remain accessible to screen
readers. This functions similarly to the aria-disabled="true" attribute.
Note: WAI-ARIA recommends elements of a larger composite widget remain focusable.
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-optionand/orpf-option-groupshere -
placeholder -
placeholder text for the select. Overrides the
placeholderattribute.
Attributes on pf-select
variant-
Variant of rendered Select
- DOM Property
variant- Type
-
'single' | 'checkbox' - Default
-
'single'
accessible-label-
Accessible label for the select
- DOM Property
accessibleLabel- Type
-
string | undefined - Default
-
unknown
accessible-current-selections-label-
Accessible label for chip group used to describe chips
- DOM Property
accessibleCurrentSelectionsLabel- Type
-
string - Default
-
'Current selections'
items-selected-text-
multi listbox button text
- DOM Property
itemsSelectedText- Type
-
string - Default
-
'items selected'
disabled-
whether select is disabled
- DOM Property
disabled- Type
-
boolean - Default
-
false
expanded-
Whether the select listbox is expanded
- DOM Property
expanded- Type
-
boolean - Default
-
false
enable-flip-
enable to flip listbox when it reaches boundary
- DOM Property
enableFlip- Type
-
boolean - Default
-
false
value-
Current form value
- DOM Property
value- Type
-
string | undefined - Default
-
unknown
placeholder-
Placeholder entry. Overridden by the
placeholderslot- DOM Property
placeholder- Type
-
string | undefined - Default
-
unknown
position-
Indicates initial popover position. There are 6 options:
bottom,top,top-start,top-end,bottom-start,bottom-end. Default isbottom.- DOM Property
position- Type
-
Placement - Default
-
'bottom'
checkbox-selection-badge-hidden-
Flag indicating if selection badge should be hidden for checkbox variant,default false
- DOM Property
checkboxSelectionBadgeHidden- Type
-
boolean - Default
-
false
Methods on pf-select
show()-
Opens the dropdown
hide()-
Closes listbox
toggle()-
toggles popup based on current state
Events on pf-select
change-
Event Type:
Event 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
-
<pf-option>or<hr>elements -
label -
Group label. Overrides the
labelattribute.
Attributes on pf-option-group
label-
Group description. Overridden by
labelslot.- DOM Property
label- Type
-
string | undefined - Default
-
unknown
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
-
unknown - Default
-
unknown
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
None
CSS Custom Properties on pf-option
None
CSS Parts on pf-option
None
