Skip to main content AWT

Dropdown

A styled dropdown for picking one option. For the device’s own dropdown, use Select. It is a real listbox, with full keyboard and screen reader support.

Live example

These are real Dropdown blocks rendering on this page right now. Tab to them and try them in both color schemes.

Closest data center.
Choose a plan.

Dark mode you don’t have to build

Every block supports dark mode. Use the light/dark toggle in the header and the live example above switches with it.

Parameters

Everything the Dropdown block accepts. Setting is the label you see in the block’s settings panel. Parameter is what the same value is called in code. Accepts is what you can put in it.

Dropdown block parameters
SettingParameterTypeDefaultAcceptsWhat it does
Typed on the blocklabelstring“Dropdown”Any textThe visible label. Screen readers announce it too, so make it say what the control does.
Placeholderplaceholderstring“Choose…”Any textGhost text inside the empty field. Never use it instead of a label.
Helper texthelperTextstringemptyAny textA short hint under the control, linked to it for screen readers.
Invalidinvalidbooleanfalsetrue or falseRenders the error state.
Invalid messageinvalidTextstringemptyAny textThe error message. It is announced to screen readers, not just colored red.
Disableddisabledbooleanfalsetrue or falseRenders the disabled state. Disabled controls are skipped by keyboard focus, so prefer hiding over disabling when you can.
Sizesizestring“md”sm, md, lgThe control height.
NamenamestringemptyAny textThe field name submitted with the form.
Options (one per line: value|label)optionsarraystructuredA listThe list of choices, one per line as label|value pairs.
Carbon defaultcarbonDefaultbooleanfalsetrue or falseUses Carbon’s own field look (a shaded fill with one line under the text) instead of AWT’s default border on all four sides.

Accessibility parameters, on this and every AWT block

Every AWT block has an Accessibility panel in its settings. Each control in it becomes a real HTML attribute on the block’s outer element:

Accessibility parameters shared by every AWT block
SettingParameterWhat it does
Accessible name (aria-label)ariaLabelBecomes aria-label on the block’s outer element. Replaces the accessible name screen readers announce. Set it only when the visible label is not enough.
Described by (aria-describedby)ariaDescribedbyBecomes aria-describedby. Point it at the ID of another element on the page whose text adds a longer description.
Labelled by (aria-labelledby)ariaLabelledbyBecomes aria-labelledby. Point it at the ID of another element whose text should become this block’s accessible name.
RoleawtRoleBecomes the role attribute. Overrides the element’s ARIA role. The list offers only roles that suit the element.
Language (lang)awtLangBecomes the lang attribute. Set it when this block’s content is in a different language from the page, as a BCP-47 code like “fr”.