Cloaked Design SystemControls

Dropdown

A compact disclosure trigger that reflects the current value and expanded state while a parent owns the associated menu or sheet.

Implementation preview

Local specification source status: preview. Implementation preview pending sign-off.

A compact disclosure trigger that reflects the current value and expanded state while a parent owns the associated menu or sheet.

Design-owned component contract ↗Version 0.2.0-preview.1 · Implementation preview pending sign-off

Implementation API 1 entry point · source-derived preview

Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.

import { Dropdown } from '@cloakedinc/design-system';

DropdownDropdownProps

packages/design-system/src/components/controls/Dropdown/Dropdown.tsx:37

Prop	Type	Presence	Notes
`label`	`string`	Required	Visible trigger text. Usually the chosen value, not a static field name.
`size`	`DropdownSize \| undefined`	Optional	Trigger size. Defaults to `'sm'`.Source default: `'sm'`
`expanded`	`boolean \| undefined`	Optional	Open state of the paired surface. Sets `aria-expanded`. Defaults to `false`.Source default: `false`
`onToggle`	`(() => void) \| undefined`	Optional	Called on press — open or close the surface here. Omitted, the button renders inert.
`haptic`	`HapticFeedback \| undefined`	Optional	Haptic feedback for trigger presses. Defaults to `true` (`light`).Source default: `true`
`className`	`string \| undefined`	Optional
`ariaLabel`	`string \| undefined`	Optional	Accessible name; falls back to the visible label when omitted.
`testId`	`string \| undefined`	Optional	Selector for the trigger button. The surface it opens carries its own.

Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.

Complete contract · JSON ↗Guidance and source · Markdown ↗

Overview

A compact trigger that shows the current value plus a chevron. It opens a picker — it is not the picker itself. You pair it with a Menu inside a BottomSheet and drive its expanded state.

When to use

Reach for Dropdown as the collapsed affordance for a value that lives elsewhere — a toolbar filter, a compact selector where a full form field would be too heavy. Dropdown owns the trigger and chevron state; the Menu you open owns the option rows (see the WithBottomSheet story).

Picking a value inside a form that should submit? Use Select — it carries form-value semantics and a hidden input.
The floating content is a list of one-off actions, not values? Open a Menu with selectionMode="none".
An always-visible switch across 2–4 options? Use SegmentedControl.

In-app it drives the activity filter in ActivityFeed.tsx, opening a Menu sheet.

Component specification

$schema

../../../specs/component-spec.schema.json

Parts

Id: trigger
Label: Trigger
Description: Native button that owns size, press, focus, and expanded semantics.

Id: label
Label: Value label
Description: Displays the current selection or filter value.

Id: chevron
Label: Chevron
Description: Rotates to communicate collapsed and expanded state.

Allowed Design Choices

Variants

Base

Label: Base
Description: One compact trigger configured through the independent size axis.

Sizes

Label: Small

Label: Medium

Variants

Id: base
Label: Base
Description: Value label and disclosure chevron; opened content remains parent-owned.
Platforms: ios
android
web

Sizes

Id: sm
Label: Small
Description: 32-unit trigger for dense toolbars.

Id: md
Label: Medium
Description: 40-unit trigger for standalone compact selection.

Measurements

Id: small-min-height
Label: Small trigger minimum height
Kind: exact
Token: --cds-size-32
Value: 32
Unit: px
Applies To: trigger
sm

Id: medium-min-height
Label: Medium trigger minimum height
Kind: exact
Token: --cds-size-40
Value: 40
Unit: px
Applies To: trigger
md

Id: content-gap
Label: Label-to-chevron gap
Kind: exact
Token: --cds-space-4
Value: 4
Unit: px
Applies To: label
chevron

Layout

Alignment: Label and chevron align on the trigger center line and the trigger hugs its content.
Flow: Current value label precedes the disclosure chevron.
Notes: Pair with Menu inside a Modal or another owned disclosure surface.
Use Select when the trigger represents a form-submitted value.

Typography And Color

Typography

Label: Value label
Description: Use body-small text at both trigger sizes.
Token: --cds-type-body-small-size

Colors

Label: Trigger surface
Description: Use the semantic page surface.
Token: --cds-bg-page

Label: Label and chevron
Description: Use primary text emphasis.
Token: --cds-text-primary

States

Id: collapsed
Label: Collapsed
Description: Shows a downward chevron and expanded false.

Id: expanded
Label: Expanded
Description: Rotates the chevron and exposes expanded true.

Id: focused
Label: Focused
Description: Retains native button focus indication and keyboard activation.

Behavior

Label: Controlled disclosure
Description: Invoke onToggle after an enabled press while the parent owns expanded state and opened content.

Label: Current value
Description: Keep the visible label synchronized with the selection represented by the paired menu.

Label: No owned popup
Description: Do not render options or manage dismissal inside Dropdown.

Accessibility

Label: Native button
Description: Expose button semantics, keyboard activation, and expanded state.

Label: Accessible name
Description: Use the visible value label unless a clearer stable accessible label is provided.

Label: Opened content
Description: The parent must name and manage focus for the associated menu, dialog, or sheet.

Content Adaptation

Label: Value labels
Description: Use concise labels that communicate the current selection rather than an instruction.

Label: Dense placement
Description: Use small in toolbars and medium when the trigger needs a clearer standalone tap target.

Motion Haptics

Motion

Label: Chevron rotation
Description: Rotate one chevron between collapsed and expanded states instead of swapping icons.

Haptics

Label: Disclosure feedback
Description: Request a light haptic after the trigger is pressed.

Platform Differences

Platforms: web
Description: Web rotates the chevron with a CSS transform while native implementations animate the equivalent platform icon.
Rationale: A single transforming affordance preserves the same expanded-state cue across rendering systems.

Implementation preview

This design-owned implementation is ready to try and review. It does not establish product approval. Imported specifications retain their original review status.

Inspect version 0.2.0-preview.1

Playground

Overview

When to use

Component specification