SelectMenu React component

A very easy to use and customisable React select dropdown.

Interactive example page

Design your own SelectMenu component here : Interactive SelectMenu example page

Features

Different types of options data :

• array of options with or without values
• array of optgroup with labels

Controlled form and uncontrolled form

• handles a custom onChange function to get the selected option's value
• handles the select native HTML behaviour

Label and SelectMenu component link

• link your select label with the SelectMenu component

Enable reset programmatically (only in V2)

Reset to default

Default selected option

• a default selected option can be set

Clear selection

• displays a button to clear the selected option

Dropdown position

• dropdown can display eather on bottom or top of the select input

Accessibility

• aria attributes
• 100% control with keyboard

Unique ID for each SelectMenu component (only in V2)

ClassNames for all essentials tags

• In V2, some classNames are added for a better CSS control.

Stylable component

• via props
• via external CSS

Installation

npm i @zafle/select_menu

Prerequisites

• NodeJS >= 20.18.0
• npm >= 10.8.1

Basic usage

The only required prop is options for a basic usage.

import { SelectMenu } from '@zafle/select_menu'

export default function App() {
  const options = ['Blue', 'Yellow', 'Green', 'Red', 'Purple']

  return <SelectMenu options={options} />
}

Advanced usage

Different types of options datas

• Options with values

To use an array of options with values, use textField and valueField props.

import { SelectMenu } from '@zafle/select_menu'

export default function App() {
  const options = [
    { option: 'Blue', code: 01 },
    { option: 'Red', code: 02 },
  ]

  return <SelectMenu options={options} textField="option" valueField="code" />
}

• Options with optGroups

To use an array of options with optGroups, use optGroupLabelField and optGroupOptionsField props.

import { SelectMenu } from '@zafle/select_menu'

export default function App() {
  const options = [
    {
      label: 'Fruits',
      options: ['Apple', 'Banana', 'Orange'],
    },
    {
      label: 'Vegetables',
      options: ['Bean', 'Pea', 'Leek'],
    },
  ]

  return (
    <SelectMenu
      options={options}
      optGroupLabelField="label"
      optGroupOptionsField="options"
    />
  )
}

• Options with optGroups and values

To use an array of options with optGroups and values, use optGroupLabelField, optGroupOptionsField, textField and valueField props.

import { SelectMenu } from '@zafle/select_menu'

export default function App() {
  const options = [
    {
      label: 'Fruits',
      options: [
        { option: 'Apple', id: 'F1' },
        { option: 'Banana', id: 'F2' },
        { option: 'Orange', id: 'F3' },
      ],
    },
    {
      label: 'Vegetables',
      options: [
        { option: 'Bean', id: 'V1' },
        { option: 'Pea', id: 'V2' },
        { option: 'Leek', id: 'V3' },
      ],
    },
  ]

  return (
    <SelectMenu
      options={options}
      optGroupLabelField="label"
      optGroupOptionsField="options"
      textField="option"
      valueField="id"
    />
  )
}

Controlled and uncontrolled Forms

• Controlled Form

To use the SelectMenu component in a controlled form, use onChangeValue prop.

import { SelectMenu } from '@zafle/select_menu'

export default function App() {
  const [selectedValue, setSelectedValue] = useState('')

  const options = ['Blue', 'Yellow', 'Green', 'Red', 'Purple']

  const handleChange = (option) => {
    setSelectedValue(option)
  }

  return (
    <>
      <p>The selected option is {selectedValue} </p>
      <SelectMenu options={options} onChangeValue={handleChange} />
    </>
  )
}

• Uncontrolled Form

To use SelectMenu in an uncontrolled form, use name prop.

import { SelectMenu } from '@zafle/select_menu'

export default function App() {
  const [formData, setFormData] = useState('')

  const options = ['Blue', 'Yellow', 'Green', 'Red', 'Purple']

  const getFormData = (e) => {
    e.preventDefault()
    setFormData(e.target.color.value)
  }

  return (
    <>
      <p>The selected option is {formData} </p>
      <form
        onSubmit={(e) => {
          getFormData(e)
        }}
      >
        <SelectMenu options={options} name="color" />
        <button type="submit">Validate</button>
      </form>
    </>
  )
}

Enable reset programmatically

In V2 only, to enable reset programmatically, the form must be controlled and the selectedOption prop is required.

• selectedOption allows to reset the SelectMenu component by clearing selection value programmatically by changing its value to null | ''.

  • null: giving a null value to selectedOption will reset the selection to the default value even when selected option === ''
  • '': giving an empty string value will not reset the selected option to its default value when selected option === '' (it will reset on empty string)

• To reset on default value (which can be set with defaultSelectedOption), set resetToDefault prop to true.

import { SelectMenu } from '@zafle/select_menu'

export default function App() {
  const [selectedValue, setSelectedValue] = useState('')

  const options = ['Blue', 'Yellow', 'Green', 'Red', 'Purple']

  const handleChange = (option) => {
    setSelectedValue(option)
  }

  const handleOnClickReset = () => {
    setSelectedValue(null)
  }

  return (
    <>
      <p>The selected option is {selectedValue} </p>
      <SelectMenu
        options={options}
        onChangeValue={handleChange}
        selectedOption={selectedValue} // Allows to reset programmatically
        defaultSelectedOption="Blue" // Optional - Set default selected option
        resetToDefault={true} // Optional
      />
      <button onClick={handleClickReset}>Reset</button>
    </>
  )
}

Label and SelectMenu component link

To link your <label> tag to the SelectMenu component, use id prop, and set htmlFor attribute in your <label> tag accordingly. This will allow a click event on the label to trigger the opening of the SelectMenu dropdown.

import { SelectMenu } from '@zafle/select_menu'

export default function App() {
  const options = ['Blue', 'Yellow', 'Green', 'Red', 'Purple']

  return (
    <>
      <label htmlFor="color-select">Choose a color</label>
      <SelectMenu options={options} id="color-select" />
    </>
  )
}

Accessibility

SelectMenu is set to display all necessary aria attributes. The whole component and its functionalities can be controlled with keyboard (tab and arrows).

For a full accessible experience set the labelId prop accordingly to the id attribute of the <label> tag to enable the aria-labelledBy attribute to be efficient.

import { SelectMenu } from '@zafle/select_menu'

export default function App() {
  const options = ['Blue', 'Yellow', 'Green', 'Red', 'Purple']

  return (
    <>
      <label id="color-select-label">Choose a color</label>
      <SelectMenu options={options} labelId="color-select-label" />
    </>
  )
}

Component props

| Prop | Description | Value example(s) | | :------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- | | optionstype: Arraydefault: none | RequiredArray of options to display in the dropdown menu. | Different types of options data | | onChangeValuetype: Functiondefault: null | Callback function triggered when an option is selected. The returned value is the selected option's value. | Controlled Form | | selectedOptiontype: stringdefault: undefined | Selected option state controlled with onChangeValue prop.NOTE: for controlled forms only. | Enable reset programmatically | | resetToDefaulttype: booleandefault: false | Indicates if the selected option must reset on default value.NOTE: for controlled forms only. | Enable reset programmatically | | nametype: stringdefault: none | Gives a name attribute to the input that will stock the value of the selected option. | Uncontrolled Form | | textFieldtype: stringdefault: none | The property name in the options array for the option's text to display. Use if the value option is different from the text option.NOTE: Must be used with valueField. | Options with values | | valueFieldtype: stringdefault: none | The property name in the options array for the option's value. Use if the value option is different from the text option.NOTE: Must be used with textField. | Options with values | | optGroupLabelFieldtype: stringdefault: none | The property name in the options array for the optGroup label.NOTE: Must be used with optGroupOptionsField. | Options with optGroups | | optGroupOptionsFieldtype: stringdefault: none | The property name in the options array for the optGroup options.NOTE: Must be used with optGroupLabelField. | Options with optGroups | | idtype: stringdefault: nanoid() | Gives a custom id attribute to the input that stocks the selected option value. | Label and SelectMenu component link | | labelIdtype: stringdefault: none | Enables the input's aria-labelledBy attribute that stocks the selected option value to be efficient. | Accessibility | | defaultSelectedOptiontype: stringdefault: undefined | Sets a default selected option. | "option*text" or "first" for first option | | maxWidth_type: string*default: "250px" | Gives the max-width CSS property for the whole component. | "200px", "50%" | | bordertype: stringdefault: "1px solid #2b2b2b" | Sets the border CSS property for the whole component. | "unset" for no border, "2px solid blue" | | borderRadiustype: stringdefault: "4px" | Sets the border-radius for the component. | "unset" for no border-radius, "10px" (single value required) | | containerMargintype: stringdefault: "0" | Defines the margin around the component. | Any valid CSS margin value ("10px", "1em", "0 auto") | | boxShadowtype: stringdefault: "4px 4px 10px rgba(0, 0, 0, 0.4)" | Sets the box-shadow of the component. | "unset" for no shadow, "4px 4px 10px black" | | boxShadowOnOpentype: booleandefault: false | Defines if the shadow appears only when the dropdown is open. | true = only when dropdown is open, false = always visible | | colorOnFocustype: stringdefault: "default" | Defines the focus color behavior. | "none" for no color on focus, "default" for browser default, Custom color | | inputHeighttype: stringdefault: "unset" | Sets the height of the select input. | Any valid CSS height value ("40px", "auto", "unset") | | inputBackgroundtype: stringdefault: "#d5d5d5" | Defines the background of the input. | Any valid CSS background value | | inputTextColortype: stringdefault: "inherit" | Sets the text color inside the input. | Any valid CSS color | | inputVerticalPaddingtype: stringdefault: "8px" | Sets the vertical padding inside the input. | Any valid CSS padding value | | inputHorizontalPaddingtype: stringdefault: "10px" | Sets the horizontal padding inside the input. | Any valid CSS padding value | | inputFontSizetype: stringdefault: "16px" | Defines the font size of the text inside the input. | Any valid CSS font-size value ("14px", "1rem") | | dropdownBackgroundtype: stringdefault: "white" | Sets the background of the dropdown menu. | Any valid CSS background value | | dropdownMaxHeighttype: stringdefault: "unset" | Defines the maximum height of the dropdown menu. | Any valid CSS max-height value ("300px", "unset") | | dropdownVerticalPaddingtype: stringdefault: "8px" | Sets the vertical padding inside the dropdown. | Any valid CSS padding value | | dropdownPositiontype: stringdefault: "bottom" | Defines whether the dropdown opens above or below the input. | "bottom" or "top" | | optionTextColortype: stringdefault: "inherit" | Sets the text color of options in the dropdown. | Any valid CSS color | | hoveredOptionBackgroundtype: stringdefault: "#484848" | Defines the background of a hovered option. | Any valid CSS background value | | hoveredOptionTextColortype: stringdefault: "white" | Defines the text color of a hovered option. | Any valid CSS color | | optionVerticalPaddingtype: stringdefault: "4px" | Sets the vertical padding of options. | Any valid CSS padding value | | optionHorizontalPaddingtype: stringdefault: "14px" | Sets the horizontal padding of options. | Any valid CSS padding value | | optionFontSizetype: stringdefault: "14px" | Defines the font size of options. | Any valid CSS font-size value | | optGroupLabelTextColortype: stringdefault: "inherit" | Sets the text color of optgroup labels. | Any valid CSS color | | optGroupLabelFontSizetype: stringdefault: "16px" | Defines the font size of optgroup labels. | Any valid CSS font-size value | | optGroupVerticalPaddingtype: stringdefault: "4px" | Sets the vertical padding of optgroup labels. | Any valid CSS padding value | | optGroupHorizontalPaddingtype: stringdefault: "10px" | Sets the horizontal padding of optgroup labels. | Any valid CSS padding value | | optGroupMarginToptype: stringdefault: "2px" | Defines the top margin of optgroup labels. | Any valid CSS margin value |

License

MIT

Author

Zafle