Photonix

Dropdown

A selectable list of items that appears when clicking a trigger element.

Preview

Profile
Usage
"use client";

import { Dropdown, type DropdownOption } from '@photonix/ultimate';
import { CalendarOutline, SettingsOutline, UserOutline } from '@photonix/icons';

const options: DropdownOption[] = [
    { value: 'profile', label: 'Profile', icon: <UserOutline /> },
    { value: 'schedule', label: 'Schedule', icon: <CalendarOutline /> },
    { value: 'settings', label: 'Settings', icon: <SettingsOutline /> },
];

export default function DropdownBasicExample() {
    return (
        <Dropdown
            label="Destination"
            placeholder="Choose a destination"
            options={options}
            defaultValue="profile"
            size="large"
            width={360}
        />
    );
}

Component API

Dropdown

Prop
Type
Default
Description
mode
"single" | "multi"
'single'
Single select mode Multi select mode
value
string | string[]
-
Current selected value. Current selected values.
defaultValue
string | string[]
-
Default value for uncontrolled mode. Default values for uncontrolled mode.
onChange
((value: string) => void) | ((values: string[]) => void)
-
Callback when the value changes. Callback when the values change.
label
string
-
Label text.
labelStyle
"inside" | "outside"
'outside'
Whether the label is placed inside or outside the input box. Default is 'outside'.
helperText
string
-
Supporting text displayed below the field.
error
boolean
-
If true, the field will be in error state.
leadingIcon
React.ReactNode
-
Icon to display at the start of the field (only for outside label).
placeholder
string
'Select...'
Placeholder text when no option is selected.
options
DropdownOption[]
[]
Options to display in the dropdown.
disabled
boolean
-
If true, the dropdown is disabled.
clearable
boolean
true
If false, hides the clear button. Default is true.
className
string
-
Additional class name.
style
React.CSSProperties
-
Additional styles.
width
string | number
-
Fixed width of the dropdown.
portal
boolean
true
Whether to render the dropdown menu in a portal. Default is true.
fullWidth
boolean
true
Whether the dropdown takes up full width of container. Default is true.
size
"large" | "medium"
'large'
Size of the dropdown. Default is 'large'.
matchWidth
boolean
true
Whether the dropdown list width should match the trigger width. Default is true.
presentation
OverlayPresentation
'auto'
Presentation mode. In auto mode, mobile viewports use a sheet and desktop uses a popover.
sheetTitle
string
-
Title used for the mobile sheet. Defaults to label or placeholder.
renderTrigger
((props: { onClick: () => void; value: string | string[]; isOpen: boolean; ref: React.RefObject<HTMLDivElement | null>; }) => React.ReactNode)
-
Slot for custom trigger. Receives props like onClick, value, isOpen.

Variants

Basic Usage

Single selection dropdown with options.

Profile
Basic Usage
"use client";

import { Dropdown, type DropdownOption } from '@photonix/ultimate';
import { CalendarOutline, SettingsOutline, UserOutline } from '@photonix/icons';

const options: DropdownOption[] = [
    { value: 'profile', label: 'Profile', icon: <UserOutline size={20} /> },
    { value: 'schedule', label: 'Schedule', icon: <CalendarOutline size={20} /> },
    { value: 'settings', label: 'Settings', icon: <SettingsOutline size={20} /> },
];

export default function DropdownBasicUsageExample() {
    return <Dropdown label="Select an option" options={options} defaultValue="profile" width="280px" />;
}

Multi-Select

Use mode='multi' to allow selecting multiple options.

2 selected
Multi-Select
"use client";

import { Dropdown } from '@photonix/ultimate';

const tags = [
    { value: 'react', label: 'React' },
    { value: 'vue', label: 'Vue' },
    { value: 'angular', label: 'Angular' },
];

export default function DropdownMultiExample() {
    return <Dropdown label="Select tags" mode="multi" placeholder="Select multiple..." options={tags} defaultValue={['react', 'vue']} width="280px" />;
}

Multi-Select with Select All

Use selectAllLabel to prepend a first option that selects or clears all visible items.

2 selected
Multi-Select with Select All
"use client";

import { Dropdown } from '@photonix/ultimate';

const tags = [
    { value: 'react', label: 'React' },
    { value: 'vue', label: 'Vue' },
    { value: 'angular', label: 'Angular' },
    { value: 'svelte', label: 'Svelte' },
];

export default function DropdownSelectAllExample() {
    return (
        <Dropdown
            label="Select tags"
            mode="multi"
            selectAllLabel="Select all tags"
            placeholder="Select multiple..."
            options={tags}
            defaultValue={['react', 'vue']}
            width="280px"
        />
    );
}

Validation

Show error states and helper text.

Select...
This field is required
Validation
"use client";

import { Dropdown, type DropdownOption } from '@photonix/ultimate';
import { CalendarOutline, SettingsOutline, UserOutline } from '@photonix/icons';

const options: DropdownOption[] = [
    { value: 'profile', label: 'Profile', icon: <UserOutline size={20} /> },
    { value: 'schedule', label: 'Schedule', icon: <CalendarOutline size={20} /> },
    { value: 'settings', label: 'Settings', icon: <SettingsOutline size={20} /> },
];

export default function DropdownValidationExample() {
    return <Dropdown label="Required Field" placeholder="Select..." options={options} error helperText="This field is required" width="280px" />;
}

Sheet Presentation

Force the mobile sheet presentation for testing responsive behavior on any viewport.

Schedule
Sheet Presentation
"use client";

import { Dropdown, type DropdownOption } from '@photonix/ultimate';
import { CalendarOutline, SettingsOutline, UserOutline } from '@photonix/icons';

const options: DropdownOption[] = [
    { value: 'profile', label: 'Profile', icon: <UserOutline size={20} /> },
    { value: 'schedule', label: 'Schedule', icon: <CalendarOutline size={20} /> },
    { value: 'settings', label: 'Settings', icon: <SettingsOutline size={20} /> },
];

export default function DropdownSheetExample() {
    return <Dropdown label="Sheet Select" sheetTitle="Choose destination" presentation="sheet" placeholder="Open as sheet..." options={options} defaultValue="schedule" width="280px" />;
}

Width & Full Width

Dropdown is full-width by default. You can set a fixed width or set fullWidth to false (auto width).

Select...
Select...
Width & Full Width
"use client";

import { Dropdown, Flex, type DropdownOption } from '@photonix/ultimate';
import { CalendarOutline, SettingsOutline, UserOutline } from '@photonix/icons';

const options: DropdownOption[] = [
    { value: 'profile', label: 'Profile', icon: <UserOutline size={20} /> },
    { value: 'schedule', label: 'Schedule', icon: <CalendarOutline size={20} /> },
    { value: 'settings', label: 'Settings', icon: <SettingsOutline size={20} /> },
];

export default function DropdownWidthExample() {
    return (
        <Flex direction="column" gap="md" w="100%">
            <Dropdown label="Auto Width" fullWidth={false} options={options} />
            <Dropdown label="Fixed Width" width="200px" options={options} />
        </Flex>
    );
}

On this page

Preview
Component API
Variants
Basic Usage
Multi-Select
Select All
Sheet Presentation
Validation
Width & Full Width
Photonix UI - React Components, Templates & Figma Design System