Skip to main content
Neighborhood Design System v5.1.0

Select

Ready

A customizable dropdown component that allows users to select one or more options from a list.

Preview

Open in Storybook (opens in new tab)

Code

Install
npm install @fbin-web/neighborhood-core
Import
import { NbhdSelect } from '@fbin-web/neighborhood-core';
Usage
<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>

Properties

PropertyAttributeTypeDefaultDescription
selectedValuesselected-valuesstring[][]Array of currently selected option values.
items—SelectOptionContent[][]Array of options to display in the select. Each item should have name and value properties.
surfacesurfacenoneprimarysecondaryinverseinverse-secondaryprimarySets the surface color treatment for the select.
multiplemultiplebooleanfalseAllows multiple options to be selected.
hidePlaceholderhide-placeholderbooleanfalseHides the placeholder and combobox when enabled.
placeholderplaceholderstringSelect an optionPlaceholder text displayed when no option is selected.
maxMultiplemax-multiplenumberundefined—Maximum number of options that can be selected when multiple is enabled.
namenamestringundefined—The name of the select for form submission. The form field name it submits under.
labellabelstring—The label text for the select.
ariaLabelaria-labelstring—Accessible name when there is no visible label. Falls back to the placeholder.
errorTexterror-textstring—Error message text to display when invalid. Defaults to "This field has an error." when empty.
helpTexthelp-textstring—Help text to provide additional context.
invalidinvalidbooleanfalseMarks the select as invalid for validation.
requiredrequiredbooleanfalseMarks the select as required: sets aria-required and shows the required marker in the label.
onNbhdChange—((event: CustomEvent) => void)undefinedundefinedCallback function triggered when the selected option(s) change.

Selection Option Content Structure

Structure of individual items in the items array

PropertyTypeRequiredDescription
namestringYesDisplay text shown to the user for this option.
valuestringYesUnique value associated with this option that gets submitted when selected.

Events

NameDescriptionEvent Detail
nbhd-selection-changedEmitted when the selected option(s) change.{ selected: string[] }
nbhd-changeEmitted when the selected option(s) change. The value is the selected values joined with commas.{ value: string }
changeEmitted 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

stops it submitting.

NameDescription
checkValidity()Returns false (and fires `invalid`) if the control fails validation.
reportValidity()Like checkValidity(), and shows the browser’s validation message on the control.
setCustomValidity(message)Marks the control invalid with your own message; an empty string clears it.
validityThe ValidityState (valueMissing, typeMismatch, customError, …).
validationMessageThe message the browser would show.
willValidateWhether the control takes part in form validation (false when disabled).
associatedFormThe
the control belongs to, or null.

Slots

NameDescription
labelCustom content for the select label. Defaults to the label property value.
helpHelp text content displayed below the select when not in an invalid state.
errorError message content displayed below the select when in an invalid state.

CSS Parts

Styleable parts exposed for CSS custom styling using ::part() selector

NameDescription
baseThe form control wrapper div.
labelThe
label-slotThe element inside the label for custom label content.
label-textThe nbhd-text component that displays the default label text.
requiredThe required marker (*) shown in the label when required. Hidden from assistive technology, which reads aria-required.
fieldThe form-control-field div wrapper containing the select input area.
selectThe main select container div that handles focus and keyboard navigation.
comboboxThe display area showing the current selection with a dropdown arrow. Visible for single-select mode and for multiple-select mode when hidePlaceholder is false.
listboxThe dropdown container that holds all selectable options (visible when open or multiple mode).
textThe wrapper div for help and error text.
helpThe help slot element.
errorThe error slot element.
limitThe message shown when maxMultiple is reached (also announced to screen readers).
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

PropertyTokenValue Copy
--nbhd-select-appearance—none
--nbhd-select-backgroundColor--nbhd-context-color-control-backgroundAdapts to surface
--nbhd-select-borderColor--nbhd-context-color-control-borderAdapts to surface
--nbhd-select-borderRadius--nbhd-border-radius-sm2px
--nbhd-select-borderStyle—solid
--nbhd-select-borderWidth--nbhd-border-width-subtle1px
--nbhd-select-combobox-inlineSize—100%
--nbhd-select-combobox-paddingBlock--nbhd-space-28px
--nbhd-select-combobox-paddingInline--nbhd-space-28px
--nbhd-select-combobox-position—relative
--nbhd-select-cursor—pointer
--nbhd-select-focus-outlineColor--nbhd-context-color-focus-outlineAdapts to surface
--nbhd-select-focus-outlineOffset--nbhd-space-00px
--nbhd-select-focus-outlineStyle--nbhd-focus-control-outlineStylesolid
--nbhd-select-focus-outlineWidth--nbhd-border-width-subtle1px
--nbhd-select-host-display—block
--nbhd-select-inlineSize—100%
--nbhd-select-minBlockSize--nbhd-size-control-xl44px
--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-heavy4px
--nbhd-select-option-hover-backgroundColor-opacity—0.05
--nbhd-select-option-inlineSize—100%
--nbhd-select-option-paddingBlock--nbhd-space-14px
--nbhd-select-option-paddingInline--nbhd-space-28px
--nbhd-select-option-selected-backgroundColor-opacity—0.1
--nbhd-select-position—relative
--nbhd-select-zIndex--nbhd-z-11

Form control

PropertyTokenValue Copy
--nbhd-formControl-display—inline
--nbhd-formControl-field-appearance—none
--nbhd-formControl-field-borderRadius--nbhd-border-radius-none0
--nbhd-formControl-field-color--nbhd-context-color-control-foregroundAdapts to surface
--nbhd-formControl-field-display—inline-block
--nbhd-formControl-field-fontFamily--nbhd-typography-body-fontFamilysans-serif
--nbhd-formControl-field-fontSize--nbhd-typography-body-fontSize1rem
--nbhd-formControl-field-inlineSize—100%
--nbhd-formControl-field-position—relative
--nbhd-formControl-fontFamily--nbhd-typography-body-fontFamilysans-serif
--nbhd-formControl-host-display—block
--nbhd-formControl-label-color--nbhd-context-color-text-primaryAdapts to surface
--nbhd-formControl-label-display—block
--nbhd-formControl-label-fontFamily--nbhd-typography-label-fontFamilysans-serif
--nbhd-formControl-label-fontSize--nbhd-typography-label-fontSize1rem
--nbhd-formControl-label-fontWeight--nbhd-typography-label-fontWeight600
--nbhd-formControl-label-letterSpacing—inherit
--nbhd-formControl-label-marginBlock--nbhd-space-0 --nbhd-space-050px 2px
--nbhd-formControl-label-position—relative
--nbhd-formControl-label-textTransform—inherit
--nbhd-formControl-marginBlock--nbhd-space-00px
--nbhd-formControl-maxInlineSize—100%
--nbhd-formControl-paddingBlock--nbhd-space-00px
--nbhd-formControl-paddingInline--nbhd-space-00px
--nbhd-formControl-position—relative
--nbhd-formControl-required-gap--nbhd-space-052px
--nbhd-formControl-text-marginBlock--nbhd-space-1 --nbhd-space-04px 0px

Dependencies

Child components <nbhd-select> renders internally. Import them too when you tree-shake.

Used by

Esc
↑ ↓ to move↵ to open