Dropdown
Opens a menu of options or actions from a trigger button. The inline dropdown uses a borderless text trigger, and the button dropdown pairs a main action with a menu of alternatives.
Default
A label, an optional
secondary_text
prefix, and the items to choose from.
<.dropdown id="dropdown-default" label="CI" secondary_text="Environment:">
<.dropdown_item value="any" label="Any" />
<.dropdown_item value="ci" label="CI">
<:right_icon><.check /></:right_icon>
</.dropdown_item>
<.dropdown_item value="local" label="Local" />
</.dropdown>
Sizes
Large is the default. Use medium in dense toolbars.
<.dropdown id="dropdown-size-large" label="Ran at" secondary_text="Sort by:">
<.dropdown_item value="ran-at" label="Ran at" />
<.dropdown_item value="duration" label="Duration" />
<.dropdown_item value="hit-rate" label="Hit rate" />
</.dropdown>
<.dropdown id="dropdown-size-medium" label="Ran at" secondary_text="Sort by:" size="medium">
<.dropdown_item value="ran-at" label="Ran at" />
<.dropdown_item value="duration" label="Duration" />
<.dropdown_item value="hit-rate" label="Hit rate" />
</.dropdown>
With icons
The
icon
slot adds an icon to the trigger. Items take
left_icon
and
right_icon
.
<.dropdown id="dropdown-icons" label="Last 30 days">
<:icon><.calendar_week /></:icon>
<.dropdown_item value="last-7-days" label="Last 7 days">
<:left_icon><.clock_hour_4 /></:left_icon>
</.dropdown_item>
<.dropdown_item value="last-30-days" label="Last 30 days">
<:left_icon><.clock_hour_4 /></:left_icon>
<:right_icon><.check /></:right_icon>
</.dropdown_item>
<.dropdown_item value="last-12-months" label="Last 12 months">
<:left_icon><.clock_hour_4 /></:left_icon>
</.dropdown_item>
</.dropdown>
Icon only
A compact trigger for row actions in tables and cards.
<.dropdown id="dropdown-icon-only" icon_only>
<:icon><.dots_vertical /></:icon>
<.dropdown_item value="edit" label="Edit endpoint">
<:left_icon><.pencil /></:left_icon>
</.dropdown_item>
<.dropdown_item value="rotate" label="Rotate secret">
<:left_icon><.reload /></:left_icon>
</.dropdown_item>
<.dropdown_separator />
<.dropdown_item value="delete" label="Delete endpoint">
<:left_icon><.trash /></:left_icon>
</.dropdown_item>
</.dropdown>
Large items
Large items show a
description
under the label.
<.dropdown id="dropdown-large-items" label="Admin">
<.dropdown_item
value="user"
label="User"
size="large"
description="Can view projects, builds, and test runs."
>
<:left_icon><.user /></:left_icon>
</.dropdown_item>
<.dropdown_item
value="admin"
label="Admin"
size="large"
description="Can also manage members, billing, and tokens."
>
<:left_icon><.users /></:left_icon>
</.dropdown_item>
</.dropdown>
Search
A search input at the top of the menu filters long lists.
<.dropdown id="dropdown-search" label="All schemes" secondary_text="Scheme:">
<:search>
<input type="text" placeholder="Search..." data-part="search-input" />
</:search>
<.dropdown_item value="all" label="All schemes" />
<.dropdown_item value="App" label="App" />
<.dropdown_item value="AppTests" label="AppTests" />
<.dropdown_item value="AppUITests" label="AppUITests" />
<.dropdown_item value="Core" label="Core" />
<.dropdown_item value="CoreTests" label="CoreTests" />
<.dropdown_item value="Networking" label="Networking" />
<.dropdown_item value="NetworkingTests" label="NetworkingTests" />
</.dropdown>
Checkboxes
Items with
checked
render a checkbox for choosing several options.
<.dropdown id="dropdown-checkboxes" label="Mon, Wed, Fri" close_on_select={false}>
<.dropdown_item value="monday" label="Monday" checked={true} />
<.dropdown_item value="tuesday" label="Tuesday" checked={false} />
<.dropdown_item value="wednesday" label="Wednesday" checked={true} />
<.dropdown_item value="thursday" label="Thursday" checked={false} />
<.dropdown_item value="friday" label="Friday" checked={true} />
</.dropdown>
Inline dropdown
The label shows the current value.
<.inline_dropdown id="inline-dropdown-default" label="English">
<.dropdown_item value="en" label="English" />
<.dropdown_item value="es" label="Español" />
<.dropdown_item value="ja" label="日本語" />
<.dropdown_item value="ko" label="한국어" />
<.dropdown_item value="ru" label="Русский" />
</.inline_dropdown>
Inline dropdown with icon
The
icon
slot adds an icon before the label.
<.inline_dropdown id="inline-dropdown-icon" label="English">
<:icon><.language /></:icon>
<.dropdown_item value="en" label="English" />
<.dropdown_item value="es" label="Español" />
<.dropdown_item value="ja" label="日本語" />
</.inline_dropdown>
Inline dropdown actions
A Manage menu for actions on the content it sits next to.
<.inline_dropdown id="inline-dropdown-actions-example" label="Manage">
<.dropdown_item value="settings" label="Connection settings">
<:left_icon><.settings /></:left_icon>
</.dropdown_item>
<.dropdown_item value="remove" label="Remove connection">
<:left_icon><.trash /></:left_icon>
</.dropdown_item>
</.inline_dropdown>
Inline dropdown disabled
<.inline_dropdown id="inline-dropdown-disabled-example" label="Manage" disabled>
<.dropdown_item value="remove" label="Remove connection" />
</.inline_dropdown>
Guidelines
-
Keep
labelto the current value and usesecondary_textfor a prefix that names what the dropdown controls, such asSort by:orEnvironment:. -
Use
patchornavigateon items when the choice belongs in the URL, such as a sort order or a filter. Useon_clickorphx-clickfor actions. -
Mark the current choice with a check in the item's
right_iconslot. -
Separate groups of items with
<.dropdown_separator />, for example to set destructive actions apart. -
For long lists, add a
:searchslot with an input that hasdata-part="search-input". The menu filters items by label and shows No results when nothing matches. -
Items with
checkedrender a checkbox, and the LiveView owns its state. Setclose_on_selecttofalseso the menu stays open while people toggle options. - Use an inline dropdown where a bordered trigger would be too heavy, such as a language switcher in a footer or a Manage menu in a card header. Its menu always closes when an item is selected.
-
In a button dropdown, make the main button the most common action and keep the menu to variations of it, such as Copy page and View as Markdown. Extra attributes such as
phx-clickgo to the main button, anddisableddisables both parts. -
Set
align="end"on a button dropdown at the right edge of its container, so the menu lines up with the button's right side.
API reference
<.dropdown>
| Attribute | Type | Default | Description |
|---|---|---|---|
|
close_on_select
|
boolean
|
true
|
Whether to close the dropdown when an item is selected
|
|
disabled
|
boolean
|
nil
|
Whether the dropdown is disabled
|
|
hint
|
string
|
nil
|
Hint text for the dropdown
|
|
icon_only
|
boolean
|
false
|
Whether the dropdown trigger is icon-only
|
|
id
Required
|
string
|
–
|
Unique identifier for the dropdown component
|
|
label
|
string
|
nil
|
Main text displayed in the dropdown trigger
|
|
on_escape_key_down
|
string
|
nil
|
Event handler for when the escape key is pressed
|
|
on_focus_outside
|
string
|
nil
|
Function called when the focus is moved outside the component
|
|
on_highlight_change
|
string
|
nil
|
Event handler for when the highlighted option changes
|
|
on_interact_outside
|
string
|
nil
|
Function called when an interaction happens outside the component
|
|
on_open_change
|
string
|
nil
|
Event handler for when the dropdown opens
|
|
on_pointer_down_outside
|
string
|
nil
|
Event handler for when the pointer is pressed outside the dropdown
|
|
on_select
|
string
|
nil
|
Event handler for when an option is selected
|
|
secondary_text
|
string
|
nil
|
Secondary text displayed to the left of the main label
|
|
size
|
string
|
"large"
|
The size of the dropdown trigger
"medium""large"
|
Also accepts global attributes.
| Slot | Description |
|---|---|
|
:icon
|
Icon to be rendered in the dropdown trigger
|
|
inner_block
|
Content to be rendered inside the dropdown menu
|
|
:search
|
Search input to be rendered at the top of the dropdown menu (outside scroll area)
|
<.dropdown_item>
| Attribute | Type | Default | Description |
|---|---|---|---|
|
checked
|
boolean
|
nil
|
When set to true or false, renders a checkbox in the checked or unchecked state. When nil (default), no checkbox is rendered.
|
|
description
|
string
|
nil
|
Additional description text (only visible when size is 'large')
|
|
href
|
string
|
nil
|
Standard URL for navigation
|
|
label
|
string
|
nil
|
Text displayed as the main content of the item
|
|
navigate
|
string
|
nil
|
Phoenix LiveView navigation path
|
|
on_click
|
string
|
nil
|
Event handler for when the dropdown item is clicked
|
|
patch
|
string
|
nil
|
Phoenix LiveView patch navigation path
|
|
secondary_text
|
string
|
nil
|
Secondary text displayed in parentheses after the label
|
|
size
|
string
|
"small"
|
Size of the dropdown item
"small""large"
|
|
value
|
string
|
–
|
Value associated with the dropdown item
|
Also accepts global attributes, including targetrel.
| Slot | Description |
|---|---|
|
:left_icon
|
Optional slot for rendering an icon on the left side of the item
|
|
:right_icon
|
Optional slot for rendering an icon on the right side of the item
|
<.inline_dropdown>
| Attribute | Type | Default | Description |
|---|---|---|---|
|
disabled
|
boolean
|
nil
|
Whether the dropdown is disabled
|
|
id
Required
|
string
|
–
|
Unique identifier for the dropdown component
|
|
label
|
string
|
nil
|
Main text displayed in the dropdown trigger
|
|
on_escape_key_down
|
string
|
nil
|
Event handler for when the escape key is pressed
|
|
on_focus_outside
|
string
|
nil
|
Function called when the focus is moved outside the component
|
|
on_highlight_change
|
string
|
nil
|
Event handler for when the highlighted option changes
|
|
on_interact_outside
|
string
|
nil
|
Function called when an interaction happens outside the component
|
|
on_open_change
|
string
|
nil
|
Event handler for when the dropdown opens
|
|
on_pointer_down_outside
|
string
|
nil
|
Event handler for when the pointer is pressed outside the dropdown
|
|
on_select
|
string
|
nil
|
Event handler for when an option is selected
|
|
size
|
string
|
"small"
|
The size of the inline dropdown trigger
"small""large"
|
Also accepts global attributes.
| Slot | Description |
|---|---|
|
:icon
|
Icon to be rendered in the dropdown trigger
|
|
inner_block
|
Content to be rendered inside the dropdown menu
|
<.button_dropdown>
Also accepts global attributes, including phx-click.