Select
ReadyA customizable dropdown component that allows users to select one or more options from a list.
Preview
Code
npm install @fbin-web/neighborhood-core
import { NbhdSelect } from '@fbin-web/neighborhood-core';
<nbhd-select
aria-label="Descriptive text about this input"
label="Select form field label"
help-text="This is some help text for the select."
error-text="Please select an option.">
</nbhd-select>
<script>
const nbhdSelect = document.querySelector('nbhd-select');
nbhdSelect.items = [
{
name: 'option 1',
value: '1',
},
{
name: 'option 2',
value: '2',
},
{
name: 'option 3',
value: '3',
},
];
</script>
npm install @fbin-web/neighborhood-react
import { NbhdSelect } from '@fbin-web/neighborhood-react';
import { NbhdSelect } from '@fbin-web/neighborhood-react';
const items = [
{
name: 'option 1',
value: '1',
},
{
name: 'option 2',
value: '2',
},
{
name: 'option 3',
value: '3',
},
];
const App = () => (
<>
<NbhdSelect
ariaLabel="Descriptive text about this input"
label="Select form field label"
helpText="This is some help text for the select."
errorText="Please select an option."
items={items}></NbhdSelect>
</>
);
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
selectedValues | selected-values | string[] | [] | Array of currently selected option values. |
items | — | SelectOptionContent[] | [] | Array of options to display in the select. Each item should have name and value properties. |
surface | surface | noneprimarysecondaryinverseinverse-secondary | primary | Sets the surface color treatment for the select. |
multiple | multiple | boolean | false | Allows multiple options to be selected. |
hidePlaceholder | hide-placeholder | boolean | false | Hides the placeholder and combobox when enabled. |
placeholder | placeholder | string | Select an option | Placeholder text displayed when no option is selected. |
maxMultiple | max-multiple | numberundefined | — | Maximum number of options that can be selected when multiple is enabled. |
name | name | stringundefined | — | The name of the select for form submission. The form field name it submits under. |
label | label | string | — | The label text for the select. |
ariaLabel | aria-label | string | — | Accessible name when there is no visible label. Falls back to the placeholder. |
errorText | error-text | string | — | Error message text to display when invalid. Defaults to "This field has an error." when empty. |
helpText | help-text | string | — | Help text to provide additional context. |
invalid | invalid | boolean | false | Marks the select as invalid for validation. |
required | required | boolean | false | Marks the select as required: sets aria-required and shows the required marker in the label. |
onNbhdChange | — | ((event: CustomEvent) => void)undefined | undefined | Callback function triggered when the selected option(s) change. |
No properties match.
Selection Option Content Structure
Structure of individual items in the items array
| Property | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Display text shown to the user for this option. |
value | string | Yes | Unique value associated with this option that gets submitted when selected. |
Events
| Name | Description | Event Detail |
|---|---|---|
nbhd-selection-changed | Emitted when the selected option(s) change. | { selected: string[] } |
nbhd-change | Emitted when the selected option(s) change. The value is the selected values joined with commas. | { value: string } |
change | Emitted alongside nbhd-change when the selected option(s) change. | { value: string } |
Form methods
Form-associated: submits the selected value under `name` (one entry per value when `multiple`). With `required`, nothing selected blocks submission. A disabled
Slots
| Name | Description |
|---|---|
label | Custom content for the select label. Defaults to the label property value. |
help | Help text content displayed below the select when not in an invalid state. |
error | Error message content displayed below the select when in an invalid state. |
CSS Parts
Styleable parts exposed for CSS custom styling using ::part() selector
| Name | Description |
|---|---|
base | The form control wrapper div. |
label | The |
label-slot | The |
label-text | The nbhd-text component that displays the default label text. |
required | The required marker (*) shown in the label when required. Hidden from assistive technology, which reads aria-required. |
field | The form-control-field div wrapper containing the select input area. |
select | The main select container div that handles focus and keyboard navigation. |
combobox | The display area showing the current selection with a dropdown arrow. Visible for single-select mode and for multiple-select mode when hidePlaceholder is false. |
listbox | The dropdown container that holds all selectable options (visible when open or multiple mode). |
text | The wrapper div for help and error text. |
help | The help slot element. |
error | The error slot element. |
limit | The message shown when maxMultiple is reached (also announced to screen readers). |
No css parts match.
nbhd-select::part(base) {
/* your styles */
}
CSS Properties
Set these on nbhd-select or an ancestor to override the defaults. Token is the design token a default comes from and Value is what it resolves to in core Neighborhood; brands may override them. Properties that adapt to surface follow the light or inverse surface they sit on until you set them.
Select
| Property | Token | Value | Copy |
|---|---|---|---|
--nbhd-select-appearance | — | none |
|
--nbhd-select-backgroundColor | --nbhd-context-color-control-background | Adapts to surface | |
--nbhd-select-borderColor | --nbhd-context-color-control-border | Adapts to surface | |
--nbhd-select-borderRadius | --nbhd-border-radius-sm | 2px |
|
--nbhd-select-borderStyle | — | solid |
|
--nbhd-select-borderWidth | --nbhd-border-width-subtle | 1px |
|
--nbhd-select-combobox-inlineSize | — | 100% |
|
--nbhd-select-combobox-paddingBlock | --nbhd-space-2 | 8px |
|
--nbhd-select-combobox-paddingInline | --nbhd-space-2 | 8px |
|
--nbhd-select-combobox-position | — | relative |
|
--nbhd-select-cursor | — | pointer |
|
--nbhd-select-focus-outlineColor | --nbhd-context-color-focus-outline | Adapts to surface | |
--nbhd-select-focus-outlineOffset | --nbhd-space-0 | 0px |
|
--nbhd-select-focus-outlineStyle | --nbhd-focus-control-outlineStyle | solid |
|
--nbhd-select-focus-outlineWidth | --nbhd-border-width-subtle | 1px |
|
--nbhd-select-host-display | — | block |
|
--nbhd-select-inlineSize | — | 100% |
|
--nbhd-select-minBlockSize | --nbhd-size-control-xl | 44px |
|
--nbhd-select-multiple-maxBlockSize | — | 300px |
|
--nbhd-select-multiple-minBlockSize | — | auto |
|
--nbhd-select-option-active-backgroundColor-opacity | — | 0.05 |
|
--nbhd-select-option-backgroundColor | — | rgb(from var(--nbhd-select-option-backgroundColor-color) r g b / var(--nbhd-select-option-backgroundColor-opacity)) |
|
--nbhd-select-option-backgroundColor-color | --nbhd-color-brand-primary | #1b5e20 |
|
--nbhd-select-option-backgroundColor-opacity | — | 0 |
|
--nbhd-select-option-borderInlineStartColor | — | transparent |
|
--nbhd-select-option-borderInlineStartStyle | — | solid |
|
--nbhd-select-option-borderInlineStartWidth | --nbhd-border-width-heavy | 4px |
|
--nbhd-select-option-hover-backgroundColor-opacity | — | 0.05 |
|
--nbhd-select-option-inlineSize | — | 100% |
|
--nbhd-select-option-paddingBlock | --nbhd-space-1 | 4px |
|
--nbhd-select-option-paddingInline | --nbhd-space-2 | 8px |
|
--nbhd-select-option-selected-backgroundColor-opacity | — | 0.1 |
|
--nbhd-select-position | — | relative |
|
--nbhd-select-zIndex | --nbhd-z-1 | 1 |
No select match.
Form control
| Property | Token | Value | Copy |
|---|---|---|---|
--nbhd-formControl-display | — | inline |
|
--nbhd-formControl-field-appearance | — | none |
|
--nbhd-formControl-field-borderRadius | --nbhd-border-radius-none | 0 |
|
--nbhd-formControl-field-color | --nbhd-context-color-control-foreground | Adapts to surface | |
--nbhd-formControl-field-display | — | inline-block |
|
--nbhd-formControl-field-fontFamily | --nbhd-typography-body-fontFamily | sans-serif |
|
--nbhd-formControl-field-fontSize | --nbhd-typography-body-fontSize | 1rem |
|
--nbhd-formControl-field-inlineSize | — | 100% |
|
--nbhd-formControl-field-position | — | relative |
|
--nbhd-formControl-fontFamily | --nbhd-typography-body-fontFamily | sans-serif |
|
--nbhd-formControl-host-display | — | block |
|
--nbhd-formControl-label-color | --nbhd-context-color-text-primary | Adapts to surface | |
--nbhd-formControl-label-display | — | block |
|
--nbhd-formControl-label-fontFamily | --nbhd-typography-label-fontFamily | sans-serif |
|
--nbhd-formControl-label-fontSize | --nbhd-typography-label-fontSize | 1rem |
|
--nbhd-formControl-label-fontWeight | --nbhd-typography-label-fontWeight | 600 |
|
--nbhd-formControl-label-letterSpacing | — | inherit |
|
--nbhd-formControl-label-marginBlock | --nbhd-space-0 --nbhd-space-05 | 0px 2px |
|
--nbhd-formControl-label-position | — | relative |
|
--nbhd-formControl-label-textTransform | — | inherit |
|
--nbhd-formControl-marginBlock | --nbhd-space-0 | 0px |
|
--nbhd-formControl-maxInlineSize | — | 100% |
|
--nbhd-formControl-paddingBlock | --nbhd-space-0 | 0px |
|
--nbhd-formControl-paddingInline | --nbhd-space-0 | 0px |
|
--nbhd-formControl-position | — | relative |
|
--nbhd-formControl-required-gap | --nbhd-space-05 | 2px |
|
--nbhd-formControl-text-marginBlock | --nbhd-space-1 --nbhd-space-0 | 4px 0px |
No form control match.
Dependencies
Child components <nbhd-select> renders internally. Import them too when you tree-shake.