Select.mdx

import { ArgTypes, Canvas, Description, Meta, Source, } from "@storybook/addon-docs/blocks";

import Banner from "../Banner/Banner"; import ComponentChangelogTable from "../../utils/ComponentChangelogTable"; import ComponentDocsHeader from "../../utils/components/ComponentDocsHeader"; import Link from "../Link/Link"; import * as SelectStories from "./Select.stories"; import { changelogData } from "./selectChangelogData";

Table of contents

• Overview
• Component props
• Accessibility
• Option elements
• Labeling variations
• Errored
• Disabled
• Autocomplete
• Getting select input value
• Changelog

Overview

Select renders a select element along with its option children. For a Select to be submitted as form data, a name attribute must be passed.

Component props

Select composes an HTML select element, so you may pass any HTML select attributes, as well any Chakra style props and the props below.

Accessibility

<Banner content={ <> RECOMMENDATION: It's recommended to pass an{" "} id value for accessibility requirements. If no{" "} id is passed, a random id will be generated. </> } mt="s" mb="s" variant="recommendation" />

The Select component renders an accessible HTML <select> element. It's the developer's responsibility to ensure that the appropriate <option> elements are provided as children.

Internally, a label is associated with the <select> element. When showLabel is set to false, the labelText will be set as the <select>'s aria-label.

Resources:

• MDN select: The HTML Select element
• Chakra UI Select

Option elements

The Select component renders all the necessary wrapping and associated text elements, but the select options need to be child <option> HTML elements.

Red Green Blue Black White `} language="jsx" />

There are two NYPL best practices when considering the number of option elements:

• Use at least four options. If fewer than three options are needed, a radio button group is a good alternative.
• Use no more than 10 options. If more than 10 options are needed, an auto-complete text input is a good alternative.

Labeling variations

A Select can be rendered with or without a visible label. If it's visible, it can be displayed above (the default) or inline with the select input using the labelPosition prop. Note that the label will only display inline when the device width exceeds the --nypl-breakpoint-medium breakpoint, or 768px. When showLabel is set to false, an aria-label attribute is added to the select input to maintain accessibility. If the component needs to be required, the showRequiredLabel prop can be used to show or hide the "required" text within the label element.

Errored

Disabled

Autocomplete

The Select component can accept all HTML autocomplete values.

Getting select input value

Controlled component using value and onChange props

If your application uses controlled React components, you can pass and extract the value through the value and onChange props. onChange will be called every time a new option is selected.

<Banner content={ <> NOTE: Open the browser console to see the value logged on each change. </> } mt="s" mb="s" variant="informative" />

{ // This will return the value selected through the event object. console.log(e.target.value); setValue(e.target.value); }; return ( Red Green Blue Black White ); } `} language="jsx" />

Uncontrolled component using refs

If your application uses uncontrolled components, you can pass a React ref prop to the DS Select component to get the selected value from the DOM. Note that this example uses a Form and a Button to submit the form. Only then will the value be available. You may pass a defaultValue prop to set the component's initial value.

<Banner content={ <> NOTE: Open the browser console to see the value logged once submitted. </> } mt="s" mb="s" variant="informative" />

{ const selectValue = selectRef.current.value; console.log("Using uncontrolled ref:", selectValue); }; return ( Red Green Blue Black White Submit ); } `} language="jsx" />

Changelog