# Dropdown

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

Version: 0.2.0-preview.1 (preview)
Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721
Contract kind: source-derived
Source: packages/design-system/src/components/controls/Dropdown/Dropdown.tsx

## Guidance

{
  "summary": "A compact disclosure trigger that reflects the current value and expanded state while a parent owns the associated menu or sheet.",
  "guidance": [
    {
      "heading": "Overview",
      "body": "A compact trigger that shows the current value plus a chevron. It **opens** a picker — it is not\nthe picker itself. You pair it with a `Menu` inside a `BottomSheet` and drive its `expanded`\nstate."
    },
    {
      "heading": "When to use",
      "body": "Reach for `Dropdown` as the collapsed affordance for a value that lives elsewhere — a toolbar\nfilter, a compact selector where a full form field would be too heavy. `Dropdown` owns the trigger\nand chevron state; the `Menu` you open owns the option rows (see the WithBottomSheet story).\n\n-   Picking a value inside a form that should submit? Use `Select` — it carries form-value semantics and a hidden input.\n-   The floating content is a list of one-off **actions**, not values? Open a `Menu` with `selectionMode=\"none\"`.\n-   An always-visible switch across 2–4 options? Use `SegmentedControl`.\n\nIn-app it drives the activity filter in `ActivityFeed.tsx`, opening a `Menu` sheet."
    }
  ],
  "usage": [],
  "examples": [],
  "source": "packages/design-system/src/components/controls/Dropdown/Dropdown.mdx",
  "status": "local-preview",
  "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification."
}

## Contract and public API

```json
{
  "props": [
    {
      "name": "label",
      "type": "string",
      "declared_type": "string",
      "required": true,
      "description": "Visible trigger text. Usually the chosen value, not a static field name.",
      "source": {
        "path": "packages/design-system/src/components/controls/Dropdown/Dropdown.tsx",
        "line": 17
      }
    },
    {
      "name": "size",
      "type": "DropdownSize | undefined",
      "declared_type": "DropdownSize",
      "required": false,
      "description": "Trigger size. Defaults to `'sm'`.",
      "source": {
        "path": "packages/design-system/src/components/controls/Dropdown/Dropdown.tsx",
        "line": 19
      },
      "values": [
        "md",
        "sm"
      ],
      "values_complete": true,
      "default": "'sm'",
      "default_kind": "source-expression"
    },
    {
      "name": "expanded",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Open state of the paired surface. Sets `aria-expanded`. Defaults to `false`.",
      "source": {
        "path": "packages/design-system/src/components/controls/Dropdown/Dropdown.tsx",
        "line": 21
      },
      "values": [
        false,
        true
      ],
      "values_complete": true,
      "default": "false",
      "default_kind": "source-expression"
    },
    {
      "name": "onToggle",
      "type": "(() => void) | undefined",
      "declared_type": "() => void",
      "required": false,
      "description": "Called on press — open or close the surface here. Omitted, the button renders inert.",
      "source": {
        "path": "packages/design-system/src/components/controls/Dropdown/Dropdown.tsx",
        "line": 23
      }
    },
    {
      "name": "haptic",
      "type": "HapticFeedback | undefined",
      "declared_type": "HapticFeedback",
      "required": false,
      "description": "Haptic feedback for trigger presses. Defaults to `true` (`light`).",
      "source": {
        "path": "packages/design-system/src/components/controls/Dropdown/Dropdown.tsx",
        "line": 25
      },
      "values": [
        "error",
        "heavy",
        "light",
        "medium",
        "selection",
        "success",
        "warning",
        false,
        true
      ],
      "values_complete": true,
      "default": "true",
      "default_kind": "source-expression"
    },
    {
      "name": "className",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/controls/Dropdown/Dropdown.tsx",
        "line": 26
      }
    },
    {
      "name": "ariaLabel",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Accessible name; falls back to the visible label when omitted.",
      "source": {
        "path": "packages/design-system/src/components/controls/Dropdown/Dropdown.tsx",
        "line": 28
      }
    },
    {
      "name": "testId",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Selector for the trigger button. The surface it opens carries its own.",
      "source": {
        "path": "packages/design-system/src/components/controls/Dropdown/Dropdown.tsx",
        "line": 30
      }
    }
  ],
  "prop_shapes": {},
  "api": {
    "method": "typescript-type-checker",
    "typescript_version": "5.9.3",
    "public_export": "Dropdown",
    "public_path": "Dropdown",
    "import_path": "@cloakedinc/design-system",
    "root_kind": "component",
    "entrypoints": [
      {
        "name": "Dropdown",
        "signature": 1,
        "visibility": "public",
        "source": {
          "path": "packages/design-system/src/components/controls/Dropdown/Dropdown.tsx",
          "line": 37
        },
        "props_type": "DropdownProps",
        "props": [
          {
            "name": "label",
            "type": "string",
            "declared_type": "string",
            "required": true,
            "description": "Visible trigger text. Usually the chosen value, not a static field name.",
            "source": {
              "path": "packages/design-system/src/components/controls/Dropdown/Dropdown.tsx",
              "line": 17
            }
          },
          {
            "name": "size",
            "type": "DropdownSize | undefined",
            "declared_type": "DropdownSize",
            "required": false,
            "description": "Trigger size. Defaults to `'sm'`.",
            "source": {
              "path": "packages/design-system/src/components/controls/Dropdown/Dropdown.tsx",
              "line": 19
            },
            "values": [
              "md",
              "sm"
            ],
            "values_complete": true,
            "default": "'sm'",
            "default_kind": "source-expression"
          },
          {
            "name": "expanded",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Open state of the paired surface. Sets `aria-expanded`. Defaults to `false`.",
            "source": {
              "path": "packages/design-system/src/components/controls/Dropdown/Dropdown.tsx",
              "line": 21
            },
            "values": [
              false,
              true
            ],
            "values_complete": true,
            "default": "false",
            "default_kind": "source-expression"
          },
          {
            "name": "onToggle",
            "type": "(() => void) | undefined",
            "declared_type": "() => void",
            "required": false,
            "description": "Called on press — open or close the surface here. Omitted, the button renders inert.",
            "source": {
              "path": "packages/design-system/src/components/controls/Dropdown/Dropdown.tsx",
              "line": 23
            }
          },
          {
            "name": "haptic",
            "type": "HapticFeedback | undefined",
            "declared_type": "HapticFeedback",
            "required": false,
            "description": "Haptic feedback for trigger presses. Defaults to `true` (`light`).",
            "source": {
              "path": "packages/design-system/src/components/controls/Dropdown/Dropdown.tsx",
              "line": 25
            },
            "values": [
              "error",
              "heavy",
              "light",
              "medium",
              "selection",
              "success",
              "warning",
              false,
              true
            ],
            "values_complete": true,
            "default": "true",
            "default_kind": "source-expression"
          },
          {
            "name": "className",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/controls/Dropdown/Dropdown.tsx",
              "line": 26
            }
          },
          {
            "name": "ariaLabel",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Accessible name; falls back to the visible label when omitted.",
            "source": {
              "path": "packages/design-system/src/components/controls/Dropdown/Dropdown.tsx",
              "line": 28
            }
          },
          {
            "name": "testId",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Selector for the trigger button. The surface it opens carries its own.",
            "source": {
              "path": "packages/design-system/src/components/controls/Dropdown/Dropdown.tsx",
              "line": 30
            }
          }
        ],
        "branches": [],
        "constraints": [],
        "extraction_status": "extracted"
      }
    ],
    "type_sources": [
      {
        "path": "packages/design-system/src/components/controls/Dropdown/Dropdown.tsx",
        "line": 9,
        "name": "DropdownSize",
        "code": "export type DropdownSize = 'sm' | 'md';"
      },
      {
        "path": "packages/design-system/src/components/controls/Dropdown/Dropdown.tsx",
        "line": 15,
        "name": "DropdownProps",
        "code": "export interface DropdownProps {\n    /** Visible trigger text. Usually the chosen value, not a static field name. */\n    label: string;\n    /** Trigger size. Defaults to `'sm'`. */\n    size?: DropdownSize;\n    /** Open state of the paired surface. Sets `aria-expanded`. Defaults to `false`. */\n    expanded?: boolean;\n    /** Called on press — open or close the surface here. Omitted, the button renders inert. */\n    onToggle?: () => void;\n    /** Haptic feedback for trigger presses. Defaults to `true` (`light`). */\n    haptic?: HapticFeedback;\n    className?: string;\n    /** Accessible name; falls back to the visible label when omitted. */\n    ariaLabel?: string;\n    /** Selector for the trigger button. The surface it opens carries its own. */\n    testId?: string;\n}"
      },
      {
        "path": "packages/design-system/src/tokens/CdsHaptic.ts",
        "line": 6,
        "name": "HapticFeedback",
        "code": "export type HapticFeedback = boolean | HapticType;"
      },
      {
        "path": "packages/design-system/src/tokens/HapticType.ts",
        "line": 2,
        "name": "HapticType",
        "code": "export type HapticType = 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error' | 'selection';"
      }
    ],
    "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source."
  },
  "spec": {
    "$schema": "../../../specs/component-spec.schema.json",
    "identity": {
      "name": "Dropdown",
      "status": "preview",
      "version": "1.0.0",
      "summary": "A compact disclosure trigger that reflects the current value and expanded state while a parent owns the associated menu or sheet."
    },
    "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."
      }
    ],
    "allowedDesignChoices": {
      "variants": {
        "base": {
          "label": "Base",
          "description": "One compact trigger configured through the independent size axis."
        }
      },
      "sizes": {
        "sm": {
          "label": "Small"
        },
        "md": {
          "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",
        "appliesTo": [
          "trigger",
          "sm"
        ]
      },
      {
        "id": "medium-min-height",
        "label": "Medium trigger minimum height",
        "kind": "exact",
        "token": "--cds-size-40",
        "value": 40,
        "unit": "px",
        "appliesTo": [
          "trigger",
          "md"
        ]
      },
      {
        "id": "content-gap",
        "label": "Label-to-chevron gap",
        "kind": "exact",
        "token": "--cds-space-4",
        "value": 4,
        "unit": "px",
        "appliesTo": [
          "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."
      ]
    },
    "typographyAndColor": {
      "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."
      }
    ],
    "contentAdaptation": [
      {
        "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."
      }
    ],
    "motionHaptics": {
      "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."
        }
      ]
    },
    "platformDifferences": [
      {
        "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."
      }
    ]
  },
  "platforms": {
    "implemented": [
      "web"
    ],
    "native": "Imported design guidance only; no native implementation or parity verification in this preview.",
    "react": {
      "implementation": "local",
      "status": "preview",
      "parity": "web-reference"
    },
    "vue": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "swift": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "kotlin": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    }
  },
  "tokens": [
    {
      "name": "--cds-size-32",
      "light": "32px",
      "dark": "32px"
    },
    {
      "name": "--cds-size-40",
      "light": "40px",
      "dark": "40px"
    },
    {
      "name": "--cds-space-4",
      "light": "4px",
      "dark": "4px"
    },
    {
      "name": "--cds-type-body-small-size",
      "light": "0.875rem",
      "dark": "0.875rem"
    },
    {
      "name": "--cds-bg-page",
      "light": "#f3f1ed",
      "dark": "#141410"
    },
    {
      "name": "--cds-text-primary",
      "light": "#141410",
      "dark": "#f3f1ed"
    }
  ],
  "review": {
    "local_status": "not-reviewed",
    "source_approval": null,
    "imported_spec_status": "approved",
    "spec_origin": "imported-adapted",
    "local_spec_source_status": "approved",
    "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1",
    "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract."
  },
  "missing_facts": [
    {
      "code": "human-review-pending",
      "detail": "This local preview has no recorded human design or engineering sign-off."
    },
    {
      "code": "platform-parity-unverified",
      "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified."
    },
    {
      "code": "figma-mapping-unverified",
      "detail": "No current component-level Figma node and immutable revision have been verified for this contract."
    }
  ]
}
```

## Visual states

- [Playground](/storybook/iframe.html?id=cloaked-design-system-controls-dropdown--playground&viewMode=story) | export: Playground | source: packages/design-system/src/components/controls/Dropdown/Dropdown.stories.tsx

- [Expanded](/storybook/iframe.html?id=cloaked-design-system-controls-dropdown--expanded&viewMode=story) | export: Expanded | source: packages/design-system/src/components/controls/Dropdown/Dropdown.stories.tsx

- [Sizes](/storybook/iframe.html?id=cloaked-design-system-controls-dropdown--sizes&viewMode=story) | export: Sizes | source: packages/design-system/src/components/controls/Dropdown/Dropdown.stories.tsx

- [With Bottom Sheet](/storybook/iframe.html?id=cloaked-design-system-controls-dropdown--with-bottom-sheet&viewMode=story) | export: WithBottomSheet | source: packages/design-system/src/components/controls/Dropdown/Dropdown.stories.tsx

- [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-controls-dropdown--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/controls/Dropdown/Dropdown.stories.tsx

Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.