Dropdown

Compact menu for actions, overflow controls, and quick commands.

Installation

npx shadcn@latest add @iconiq/r-dropdown

File Structure

Usage

"use client";

import { Dropdown, DropdownContent, DropdownItem, DropdownTrigger, DropdownValue } from "@/components/ui/r-dropdown";
import { useState } from "react";

export function DropdownPreview() {
  const [open, setOpen] = useState(false);
  const [team, setTeam] = useState<string | undefined>("design");
  return (
    <Dropdown onOpenChange={setOpen} open={open} onValueChange={setTeam} value={team} className="w-[220px]">
      <DropdownTrigger className="border-neutral-200 shadow-none hover:border-neutral-200 dark:border-neutral-800 dark:hover:border-neutral-800">
        <DropdownValue placeholder="Choose a team" />
      </DropdownTrigger>
      <DropdownContent className="w-full">
          <DropdownItem value="design">Design</DropdownItem>
          <DropdownItem value="product">Product</DropdownItem>
          <DropdownItem value="engineering">Engineering</DropdownItem>
          <DropdownItem value="finance">Finance</DropdownItem>
          <DropdownItem value="people">People Ops</DropdownItem>
          <DropdownItem value="legal">Legal</DropdownItem>
      </DropdownContent>
    </Dropdown>
  );
}

Props

Props
Description

Dropdown

children

Compose DropdownTrigger, DropdownContent, DropdownItem, and optional helpers like DropdownValue, DropdownSeparator, or DropdownSub inside the root.

Type ReactNode

value

Controlled selected value for the select variant. Action mode usually leaves this unset.

Type string

defaultValue

Initial selected value for uncontrolled select usage.

Type string

onValueChange

Called when a select item updates the current value.

Type (value: string | undefined) => void

open

Controlled open state for the menu surface.

Type boolean

defaultOpen

Initial open state for uncontrolled usage.

Type boolean·Default false

onOpenChange

Called whenever the trigger, outside click handling, or Escape key changes the open state.

Type (open: boolean) => void

variant

Use select when items should commit a persistent value with a checkmark, or action when items should behave like immediate commands. For form fields, prefer the dedicated r-select install.

Type "select" | "action"·Default select

modal

When true, Radix traps focus and blocks outside interaction while the menu is open.

Type boolean·Default false

disabled

Disables the trigger and prevents opening the menu from the root.

Type boolean·Default false

name

Optional form field name. In select mode, renders a hidden input that submits the current value.

Type string

required

Marks the hidden select input as required when name is provided.

Type boolean

className

Merged onto the outer relative wrapper around the trigger and content.

Type string

DropdownTrigger

children

Trigger content. In select mode this usually includes DropdownValue, while action menus can pass custom content such as an avatar or label row.

Type ReactNode

showChevron

Hides the default chevron when you want a cleaner custom trigger, such as an avatar-only action menu.

Type boolean·Default true

triggerShape

Use avatar to skip squircle corner styling on circular image triggers.

Type "default" | "avatar"·Default default

className

Merged onto the trigger button shell.

Type string

disabled

Prevents opening and dims the trigger styling. Root disabled also applies when this prop is omitted.

Type boolean

DropdownValue

placeholder

Text shown when no matching selected value is currently registered.

Type string·Default "Select an option"

className

Merged onto the rendered span inside the trigger.

Type string

DropdownContent

children

Usually DropdownItem children, with optional DropdownSeparator nodes between groups.

Type ReactNode

align

Alignment relative to the trigger along the cross axis.

Type "start" | "center" | "end"·Default start

side

Preferred placement relative to the trigger.

Type "top" | "right" | "bottom" | "left"·Default bottom

avoidCollisions

When true, Radix flips or shifts the menu to stay inside the viewport.

Type boolean·Default true

sideOffset

Gap between the trigger and the dropdown surface.

Type number·Default 8

className

Merged onto the dropdown surface, which is useful for setting a custom width or changing shadows in docs/examples.

Type string

DropdownItem

children

Row content. You can place icons inline before the label for action menus or richer item layouts.

Type ReactNode

value

Selection key for select mode. When it matches the root value, the item renders the checkmark state.

Type string

textValue

Optional explicit label used by DropdownValue and typeahead when your item children are not plain text.

Type string

onClick

Runs before the item closes the menu. Action menus typically use this for immediate commands like profile or logout.

Type (event: MouseEvent<HTMLDivElement>) => void

disabled

Prevents interaction and dims the row.

Type boolean

DropdownCheckboxItem

children

Row label and optional leading icon.

Type ReactNode

checked

Controlled checked state for the row.

Type boolean | 'indeterminate'

onCheckedChange

Called when the row toggles checked state.

Type (checked: boolean) => void

disabled

Prevents interaction and dims the row.

Type boolean

className

Merged onto the checkbox row shell.

Type string

DropdownRadioGroup

children

Usually DropdownRadioItem children.

Type ReactNode

value

Controlled selected value for the radio group.

Type string

onValueChange

Called when a radio item is chosen.

Type (value: string) => void

DropdownRadioItem

children

Row label and optional leading icon.

Type ReactNode

value

Radio value committed when the row is chosen.

Type string

textValue

Optional explicit label used by DropdownValue and typeahead.

Type string

disabled

Prevents interaction and dims the row.

Type boolean

DropdownSub

children

DropdownSubTrigger followed by DropdownSubContent.

Type ReactNode

DropdownShortcut

children

Shortcut text such as ⌘K or Ctrl+S.

Type ReactNode

className

Merged onto the shortcut span.

Type string

DropdownGroup

children

Usually one or more DropdownItem nodes. Add label when you want a visible heading, or omit it when you just want grouped spacing.

Type ReactNode

label

Optional convenience heading rendered with DropdownLabel styling and linked to the group for assistive technologies.

Type ReactNode

labelClassName

Merged onto the generated section heading when you want to tweak its spacing or tone.

Type string

className

Merged onto the group wrapper. The base version adds light vertical spacing between grouped rows.

Type string

DropdownLabel

children

Short section text such as Product, Billing, or Workspace settings.

Type ReactNode

className

Merged onto the rendered div when you want to adjust spacing, weight, or casing locally.

Type string

DropdownSeparator

className

Merged onto the divider element when you want to adjust spacing or tone locally.

Type string

Registry bundle

Install the exact registry entry shown on the right when you want the component file and its declared runtime dependencies together.

Dependencies: @radix-ui/react-dropdown-menu, @radix-ui/react-scroll-area, motion, lucide-react.

This page documents the Radix UI install only. Base UI does not ship an equivalent dropdown menu primitive in this comparison set.

Shadcn-style aliases such as DropdownMenu and DropdownMenuItem are exported from the same file.

The generated registry file is /r/r-dropdown.json.

Contact

Additionally, if you find any bug or issue, feel free to raise an issue.

Pick a team from grouped rows with keyboard, scroll, and selection feedback.