Dropdown

The Dropdown component allows you to create a dropdown menu with selectable options. It works seamlessly with the Dropdown.Options and Dropdown.Option slots.

For detailed information about the Dropdown.Options and Dropdown.Option slots, refer to the Dropdown.Options documentation.

Usage

To implement a dropdown in your UI, wrap the Dropdown.Options and Dropdown.Option slots within the Dropdown component:

index.tsx

import Dropdown from '@components/Basic/Dropdown/Dropdown';

<Dropdown style={{ width: '10rem' }}>
    <Dropdown.Options>
        <Dropdown.Option selected value="red">red</Dropdown.Option>
        <Dropdown.Option value="green">green</Dropdown.Option>
        <Dropdown.Option value="blue">blue</Dropdown.Option>
    </Dropdown.Options>
</Dropdown>

API

Props

Prop Name	Type	Default	Description
style	JSX.CSSProperties	{}	Inline styles to apply directly to the component’s root element.
class	string	""	Additional CSS classes to apply to the component.
ref	DropdownRef | undefined	undefined	A reference to the component, providing access to its methods and underlying HTML element for programmatic control.
disabled	boolean	false	Disables the dropdown when set to true.
class-disabled	string	""	Additional CSS classes to apply when the dropdown is disabled.
multiple	boolean	false	Enables multi-select mode. When true, selecting an option toggles it on or off, the options panel stays open after a selection, and onChange reports an array of values.
value	string | string[]	undefined	The selected value(s) of the dropdown. Pass a string (or a string[] when multiple is enabled) to control or set the selection. The prop is reactive - updating it externally changes the selection. Values that don’t match a registered option are ignored. When provided, it takes precedence over the selected prop on Dropdown.Option.
onChange	(value: string | string[]) => void	undefined	Callback function triggered whenever the selection changes. Provides the selected option’s value, or an array of selected values when multiple is enabled.
onAction	Record<string, (scope?: string, ...args: any[]) => void>	undefined	Extends or overrides the component’s default navigation action handlers. See Implemented Navigation Actions for details.
anchor	string | HTMLElement	undefined	Links navigation to another element. When the anchor element is focused, the dropdown’s actions will execute. Can be a CSS selector or HTMLElement.

Ref API

To interact with the Dropdown programmatically, you can use the DropdownRef interface. This interface provides properties and methods to access and manipulate the component’s state.

Properties

Property	Type	Description
selected	Accessor<string>	Read the currently selected option: ref.selected() returns the value.
selectedValues	Accessor<string[]>	Read all currently selected values when the dropdown is in multiple mode: ref.selectedValues() returns the array of values.
element	HTMLDivElement	A reference to the dropdown’s root HTML element, useful for DOM access or styling.

Methods

Method	Parameters	Return Value	Description
selectOption	value: string	void	Selects an option programmatically. In multiple mode, calling it with an already-selected value toggles it off.
deselectOption	value: string	void	Deselects a single option by its value.
deselectAll	none	void	Clears every selected option in one call, firing onChange once with the empty result.
toggle	isOpened: boolean	void	Programmatically opens (true) or closes (false) the dropdown’s options panel.

Slots

Dropdown.Trigger

The Dropdown.Trigger slot allows you to customize the dropdown’s trigger button, which toggles the dropdown’s open or closed state when clicked. Use this slot to modify the trigger’s appearance by applying custom styles or CSS classes.

Properties

Prop Name	Type	Default	Description
style	JSX.CSSProperties	{}	Inline styles to apply directly to the trigger element.
class	string	""	Additional CSS classes to apply to the trigger element.

Usage

import Dropdown from '@components/Basic/Dropdown/Dropdown';

const App = () => {
    return (
        <Dropdown>
            <Dropdown.Options>
                <Dropdown.Option selected value="red">red</Dropdown.Option>
                <Dropdown.Option value="green">green</Dropdown.Option>
                <Dropdown.Option value="blue">blue</Dropdown.Option>
            </Dropdown.Options>
            <Dropdown.Trigger style={{ background: '#cccccc' }}/>
        </Dropdown>
    );
};

export default App;

Dropdown.Placeholder

The Dropdown.Placeholder slot allows you to display a placeholder when no option is selected in the dropdown. If this slot is not used, no placeholder will be shown by default.

Note

To display the default placeholder with the text Select an option, include the <Dropdown.Placeholder/> as a direct child of the <Dropdown> component.

Note

To use a custom placeholder, include the <Dropdown.Placeholder> slot with your desired content, such as <Dropdown.Placeholder>Select any option</Dropdown.Placeholder>.

Properties

Prop Name	Type	Default	Description
style	JSX.CSSProperties	{}	Inline styles to apply directly to the placeholder element.
class	string	""	Additional CSS classes to apply to the placeholder element.
children	JSX.Element	""	Content to display when no option is selected, such as text or JSX.

Usage

import Dropdown from '@components/Basic/Dropdown/Dropdown';

const App = () => {
    return (
        <Dropdown>
            <Dropdown.Options>
                <Dropdown.Option value="red">red</Dropdown.Option>
                <Dropdown.Option value="green">green</Dropdown.Option>
                <Dropdown.Option value="blue">blue</Dropdown.Option>
            </Dropdown.Options>
            <Dropdown.Placeholder style={{ color: '#cccccc' }}>Select any option</Dropdown.Placeholder>
        </Dropdown>
    );
};

export default App;

Dropdown.Icon

The Dropdown.Icon slot allows you to add or customize the icon displayed inside the dropdown’s trigger, typically on the right side.

Note

To use the default icon, include the <Dropdown.Icon/> slot as a child of the <Dropdown> component.

Note

To use a custom icon, provide your desired content as children of the Dropdown.Icon slot:

<Dropdown.Icon>
    <svg>
        ...
    </svg>
</Dropdown.Icon>

Properties

Prop Name	Type	Default	Description
style	JSX.CSSProperties	{}	Inline styles to apply directly to the dropdown trigger’s icon element.
class	string	""	Additional CSS classes to apply to the dropdown trigger’s icon element.
children	JSX.Element	""	Custom content, such as text, HTML, or JSX, to render as the dropdown icon.

Usage

import Dropdown from '@components/Basic/Dropdown/Dropdown';

const App = () => {
    return (
        <Dropdown>
            <Dropdown.Options>
                <Dropdown.Option selected value="red">red</Dropdown.Option>
                <Dropdown.Option value="green">green</Dropdown.Option>
                <Dropdown.Option value="blue">blue</Dropdown.Option>
            </Dropdown.Options>
            <Dropdown.Icon style={{ background: '#cccccc' }}>
                <img src="my-custom-icon.png" />
            </Dropdown.Icon>
        </Dropdown>
    );
};

export default App;

Dropdown.Track

The Dropdown.Track slot enables you to customize the scroll track of the dropdown when the options overflow the container.

Properties

Prop Name	Type	Default	Description
style	JSX.CSSProperties	{}	Inline styles to apply directly to the dropdown’s track element.
class	string	""	Additional CSS classes to apply to the dropdown’s track element.
children	JSX.Element	""	Custom content, such as text, HTML, or JSX, to render inside the track.

Usage

import Dropdown from '@components/Basic/Dropdown/Dropdown';

const App = () => {
    return (
        <Dropdown>
            <Dropdown.Options>
                <Dropdown.Option selected value="red">red</Dropdown.Option>
                <Dropdown.Option value="green">green</Dropdown.Option>
                <Dropdown.Option value="blue">blue</Dropdown.Option>
            </Dropdown.Options>
            <Dropdown.Track style={{ background: '#cccccc' }}/>
        </Dropdown>
    );
};

export default App;

Tip

To hide the Dropdown.Track, you can set its display style to none:

<Dropdown.Track style={{ display: 'none' }}/>

Dropdown.Handle

The Dropdown.Handle slot lets you customize the scroll handle for the dropdown when the options overflow the container.

Properties

Prop Name	Type	Default	Description
style	JSX.CSSProperties	{}	Inline styles to apply directly to the handle element.
class	string	""	Additional CSS classes to apply to the handle element.
children	JSX.Element	""	Custom content, such as text, HTML, or JSX, to render inside the handle.

Usage

import Dropdown from '@components/Basic/Dropdown/Dropdown';

const App = () => {
    return (
        <Dropdown>
            <Dropdown.Options>
                <Dropdown.Option selected value="red">red</Dropdown.Option>
                <Dropdown.Option value="green">green</Dropdown.Option>
                <Dropdown.Option value="blue">blue</Dropdown.Option>
            </Dropdown.Options>
            <Dropdown.Handle style={{ background: '#cccccc' }}/>
        </Dropdown>
    );
};

export default App;

Tip

To hide the Dropdown.Handle, set its display style to none:

<Dropdown.Handle style={{ display: 'none' }}/>

Implemented Navigation Actions

The Dropdown component implements the following navigation actions by default:

Action Name	Behavior
select	Opens the dropdown when closed. When open, collapses the dropdown (options handle selection)
back	Closes the dropdown and returns focus to the trigger or anchor element

You can extend the Dropdown with additional navigation actions or override the default behavior using the onAction prop:

import Dropdown from '@components/Basic/Dropdown/Dropdown';

<Dropdown
    onAction={{
        'select': () => console.log('Custom select behavior!'),
        'back': () => console.log('Custom back behavior!')
    }}
>
    <Dropdown.Options>
        <Dropdown.Option value="red">red</Dropdown.Option>
        <Dropdown.Option value="green">green</Dropdown.Option>
        <Dropdown.Option value="blue">blue</Dropdown.Option>
    </Dropdown.Options>
</Dropdown>

Caution

Every Dropdown.Option component is listening for the select action to handle option selection. This action cannot be overriden.

For more information about navigation actions, check the Navigation component documentation.

Guide

Retrieve the selected option’s value on change

To capture the value of the selected option:

• Use the onChange prop to handle changes in the selected option.

Steps

1. Pass a callback function to the onChange prop to handle state updates.
2. Access the selected option’s value through the selected parameter in the callback.

import Dropdown from '@components/Basic/Dropdown/Dropdown';

const App = () => {
    const handleSelectionChange = (selected: string) => {
        console.log(selected);
    };

    return (
        <Dropdown onChange={handleSelectionChange}>
            <Dropdown.Options>
                <Dropdown.Option selected value="red">red</Dropdown.Option>
                <Dropdown.Option value="green">green</Dropdown.Option>
                <Dropdown.Option value="blue">blue</Dropdown.Option>
            </Dropdown.Options>
        </Dropdown>
    );
};

export default App;

Allow selecting multiple options

To let users select more than one option at a time, enable the multiple prop.

Behavior

• Clicking an option toggles it on or off instead of replacing the current selection.
• The options panel stays open after a selection so several options can be picked in a row.
• onChange receives an array of the selected values.

import Dropdown from '@components/Basic/Dropdown/Dropdown';

const App = () => {
    const handleSelectionChange = (selected: string[]) => {
        console.log(selected); // e.g. ["red", "blue"]
    };

    return (
        <Dropdown multiple onChange={handleSelectionChange}>
            <Dropdown.Options>
                <Dropdown.Option value="red">red</Dropdown.Option>
                <Dropdown.Option value="green">green</Dropdown.Option>
                <Dropdown.Option value="blue">blue</Dropdown.Option>
            </Dropdown.Options>
        </Dropdown>
    );
};

export default App;

Note

In multiple mode, read the current selection with ref.selectedValues() and clear it with ref.deselectAll().

Control the selected value (two-way binding)

The value prop is reactive: pass a signal to it and update that signal from onChange to keep your state and the dropdown in sync in both directions.

• Updating the signal externally moves the selection (state → dropdown).
• Selecting an option in the UI fires onChange, which updates the signal (dropdown → state).

Steps

1. Create a signal to hold the selected value.
2. Bind it to the value prop.
3. Update it from the onChange callback.

import Dropdown from '@components/Basic/Dropdown/Dropdown';
import { createSignal } from 'solid-js';

const App = () => {
    const [selected, setSelected] = createSignal('red');

    return (
        <>
            <Dropdown value={selected()} onChange={(value) => setSelected(value as string)}>
                <Dropdown.Options>
                    <Dropdown.Option value="red">red</Dropdown.Option>
                    <Dropdown.Option value="green">green</Dropdown.Option>
                    <Dropdown.Option value="blue">blue</Dropdown.Option>
                </Dropdown.Options>
            </Dropdown>

            {/* Updating the signal here also moves the dropdown's selection */}
            <button onClick={() => setSelected('blue')}>Select blue</button>
        </>
    );
};

export default App;

In multiple mode, bind value to a string[] signal instead. Any values that don’t match a registered option are filtered out:

const [selected, setSelected] = createSignal<string[]>(['red', 'blue']);

<Dropdown multiple value={selected()} onChange={(value) => setSelected(value as string[])}>
    <Dropdown.Options>
        <Dropdown.Option value="red">red</Dropdown.Option>
        <Dropdown.Option value="green">green</Dropdown.Option>
        <Dropdown.Option value="blue">blue</Dropdown.Option>
    </Dropdown.Options>
</Dropdown>

Note

When value is provided, it is the source of truth for the selection and overrides the selected prop on individual Dropdown.Option slots.

Programmatically set the selected option

The Dropdown component allows you to programmatically update the selected option.

Steps

1. Create a ref variable of type DropdownRef and assign it to the Dropdown component.
2. Use the ref.selectOption() method to programmatically set a new selected option, such as in response to a button click or keyboard event.

import Dropdown, { DropdownRef } from '@components/Basic/Dropdown/Dropdown';

const App = () => {
    let dropdownRef!: DropdownRef;

    const handleKeyPress = (e: KeyboardEvent) => {
        if (e.keyCode !== 13) return

        dropdownRef.selectOption('green');
    };

    return (
        <Dropdown ref={dropdownRef} keypress={handleKeyPress}>
            <Dropdown.Options>
                <Dropdown.Option selected value="red">red</Dropdown.Option>
                <Dropdown.Option value="green">green</Dropdown.Option>
                <Dropdown.Option value="blue">blue</Dropdown.Option>
            </Dropdown.Options>
        </Dropdown>
    );
};

export default App;