Dropdown Component

Dropdowns are a common form control that allows the user to select from a list of options.

Users can click on the dropdown to display a list of options, or start typing to fuzzy-find to jump directly to their choice within a larger lists of options.

Dropdowns emit the change event when their selection changes. When disabled, the user will not be able to change the value of a dropdown, and no change events will be emitted.

Properties

Visible

Prop	`isVisible`
Type	`boolean`
Default	`true`

Whether or not this node is visible.

Enabled

Prop	`isEnabled`
Type	`boolean`
Default	`true`

Whether or not this node is enabled.

Tooltip

Prop	`tooltip`
Type	`string`
Default	`undefined`

The tooltip text to display when hovered or focused over this node.

Top

Prop	`top`
Type	`number`
Default	`1`

The position of the node from the top side of the grid (grid-row-start).

Left

Prop	`left`
Type	`number`
Default	`1`

The position of the node from the left side of the grid (grid-column-start).

Width

Prop	`width`
Type	`string`
Default	`232px`

The width of the node. When this node is in a grid layout, this should be done using unitless grid column units (specifying 4 will become grid-column-end: span 4). When this node is in a stack layout, the width can be specified using CSS units (e.g. 100px or 100%), or be left unitless to be treated as flex-grow for the node.

Min Width

Prop	`minWidth`
Type	`string`
Default	`undefined`

The minimum width of the node. When this node is in a grid layout, this property is ignored.

Max Width

Prop	`maxWidth`
Type	`string`
Default	`undefined`

The maximum width of the node. When this node is in a grid layout, this property is ignored.

Height

Prop	`height`
Type	`string`
Default	`64px`

The height of the node. When this node is in a grid layout, this should be done using unitless grid row units (specifying 4 will become grid-row-end: span 4). When this node is in a stack layout, the height can be specified using CSS units (e.g. 100px or 100%), or be left unitless to be treated as flex-grow for the node.

Min Height

Prop	`minHeight`
Type	`string`
Default	`undefined`

The minimum height of the node. When this node is in a grid layout, this property is ignored.

Max Height

Prop	`maxHeight`
Type	`string`
Default	`undefined`

The minimum height of the node. When this node is in a grid layout, this property is ignored.

Overflow

Prop	`overflow`
Type	`Overflow ('auto' \| 'visible' \| 'hidden' \| 'scroll')`
Default	`auto`

The strategy used to handle overflow in the horizontal and vertical axes for content that is larger than its container.

Overflow X

Prop	`overflowX`
Type	`Overflow ('auto' \| 'visible' \| 'hidden' \| 'scroll')`
Default	`auto`

The strategy used to handle overflow in the horizontal axis for content that is larger than its container.

Overflow Y

Prop	`overflowY`
Type	`Overflow ('auto' \| 'visible' \| 'hidden' \| 'scroll')`
Default	`auto`

The strategy used to handle overflow in the vertical axis for content that is larger than its container.

Custom Styles

Prop	`styles`
Type	`string`
Default	`::component { }`

Custom CSS styles to be applied to the node. Use element.styles to refer to the current node.

Object Fit

Prop	`objectFit`
Type	`ObjectFit ('none' \| 'contain' \| 'cover' \| 'fill' \| 'scale-down')`
Default	`cover`

The strategy used to set how the content of a replaced element should be resized to fit its container.

Field Name

Prop	`formFieldName`
Type	`string`
Default	`undefined`

Defines the key for this input in the body of the submitted form.

Label

Prop	`label`
Type	`string`
Default	`Select one`

The label to be displayed alongside the dropdown.

Values

Prop	`values`
Type	`Array<unknown>`
Default	`{{[1, 2, 3]}}`

The array of values that the user is able to choose from. Values can be any TypeScript value, including objects. Often, it is useful to display a human-readable string to the user of a dropdown using the displayValues property, and instead use a machine-readable value in this property, such as an ID or row object.

Display Values

Prop	`displayValues`
Type	`Array<string>`
Default	`undefined`

The array of human-readable displayed values that the user is able to choose from. This array should have the same length as values, but must contain only strings.

Selected Value

Prop	`value`
Type	`unknown`
Default	`undefined`

The selected value of the dropdown. This can be one of the options from values, or undefined when no value is selected.

Placeholder

Prop	`placeholder`
Type	`string`
Default	`undefined`

The placeholder value to display when no option has been selected.

Enable

Prop	`enableFilter`
Type	`boolean`
Default	`false`

Whether or not to enable filtering of (options)[#display-values] as user types.

Fuzzy Matching

Prop	`fuzzyMatching`
Type	`boolean`
Default	`true`

Whether or not to enable fuzzy-find matching of dropdown items when using the keyboard.

Case-sensitive Matching

Prop	`caseSensitiveMatching`
Type	`boolean`
Default	`false`

Whether or not to enable case-sensitive matching of dropdown items when using the keyboard.

Required

Prop	`isRequired`
Type	`boolean`
Default	`false`

Whether or not this dropdown is required. This is a visual flag that updates the corresponding accessibility properties. It is up to the app developer to enforce the requirement.

Allow Clearing

Prop	`allowClearing`
Type	`boolean`
Default	`true`

Whether or not to allow clearing of the dropdown after a selection has been made. This will reset the dropdown's (value)[#value].

Label Style

Prop	`labelStyle`
Type	`DropdownLabelStyle ('left' \| 'top' \| 'hidden' \| 'right')`
Default	`top`

The display style of the label next to the dropdown.

Label Width

Prop	`labelWidth`
Type	`string`
Default	`35%`

The width of the label.

Prop	`fontSize`
Type	`CheckboxSize ('xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| '4xl')`
Default	`md`

Background Color

Prop	`backgroundColor`
Type	`string`
Default	`input.background`

The background color of the dropdown.

Label Color

Prop	`labelColor`
Type	`string`
Default	`text.primary`

The color of the label text.

Input Color

Prop	`inputColor`
Type	`string`
Default	`text.primary`

The color of the input text.

Placeholder Color

Prop	`placeholderColor`
Type	`string`
Default	`input.placeholder`

The color of the placeholder text.

Event Handlers

On Hover

Handler	`dropdownNode.onHover`

Called when the user hovers on the node. Use this event to trigger downstream actions when this node is hovered.

On Leave

Handler	`dropdownNode.onLeave`

Called when the user is not hovering over the node. Use this event to trigger downstream actions when this node is no longer hovered.

On Focus

Handler	`dropdownNode.onFocus`

Called when the user focuses the node. Use this event to trigger downstream actions when this node is focused.

On Blur

Handler	`dropdownNode.onBlur`

Called when the user blurs the node. Use this event to trigger downstream actions when this node is blurred.

On Change

Handler	`dropdownNode.onChange`

Called when the selected dropdown option changes.

Data Table File Input