---
components: ["Dropdown", "DropdownSkeleton"]
---

<script>
  import { Dropdown, DropdownSkeleton, InlineNotification } from "carbon-components-svelte";
  import Preview from "../../components/Preview.svelte";
</script>

The `Dropdown` component provides a select input with a dropdown menu. It supports
various states, sizes, and customization options. Each item in the dropdown must
have a unique `id` property for proper functionality.

<InlineNotification svx-ignore lowContrast title="Note:" kind="info" hideCloseButton>
  <div class="body-short-01">Every <code>items</code> object must have a unique "id" property.</div>
</InlineNotification>

## Default

Use the `Dropdown` component to create a select input with a dropdown menu. Each item
must have a unique `id` property.

<Dropdown titleText="Contact" selectedId="0" items="{[{id: "0", text: "Slack"},
  {id: "1", text: "Email"},
  {id: "2", text: "Fax"}]}" />

## Custom slot

Override the default slot to customize the display of each item. Access the item and
index through the `let:` directive.

<FileSource src="/framed/Dropdown/DropdownSlot" />

## Hidden label

Hide the label while maintaining accessibility by setting the `hideLabel` prop to
`true`. The label will still be available to screen readers.

<Dropdown hideLabel titleText="Contact" selectedId="0" items="{[{id: "0", text: "Slack"},
  {id: "1", text: "Email"},
  {id: "2", text: "Fax"}]}" />

## Format item display text

Format the display text of items using the `itemToString` prop. This function
receives the item object and returns the formatted string.

<Dropdown itemToString={item => {
  return item.text + ' (' + item.id +')'
}} titleText="Contact" selectedId="0" items="{[{id: "0", text: "Slack"},
  {id: "1", text: "Email"},
  {id: "2", text: "Fax"}]}" />

## Multiple dropdowns

Create multiple dropdowns that work together. This example demonstrates how to
manage the state of multiple dropdowns.

<FileSource src="/framed/Dropdown/MultipleDropdown" />

## Top direction

Display the dropdown menu above the input by setting the `direction` prop to
`"top"`. This is useful when there's limited space below the input.

<Dropdown direction="top" titleText="Contact" selectedId="0" items="{[{id: "0", text: "Slack"},
  {id: "1", text: "Email"},
  {id: "2", text: "Fax"}]}" />

## Light variant

Use the light variant for dropdowns on dark backgrounds by setting the `light` prop
to `true`.

<Dropdown light titleText="Contact" selectedId="0" items="{[{id: "0", text: "Slack"},
  {id: "1", text: "Email"},
  {id: "2", text: "Fax"}]}" />

## Inline variant

Display the dropdown inline with other content by setting the `type` prop to
`"inline"`. This variant removes the background and border.

<Dropdown type="inline" titleText="Contact" selectedId="0" items="{[{id: "0", text: "Slack"},
  {id: "1", text: "Email"},
  {id: "2", text: "Fax"}]}" />

## Extra-large size

Increase the size of the dropdown by setting the `size` prop to `"xl"`. This
provides more visual emphasis for important selections.

<Dropdown size="xl" titleText="Contact" selectedId="0" items="{[{id: "0", text: "Slack"},
  {id: "1", text: "Email"},
  {id: "2", text: "Fax"}]}" />

## Small size

Decrease the size of the dropdown by setting the `size` prop to `"sm"`. This is
useful for compact layouts or secondary selections.

<Dropdown size="sm" titleText="Contact" selectedId="0" items="{[{id: "0", text: "Slack"},
  {id: "1", text: "Email"},
  {id: "2", text: "Fax"}]}" />

## Invalid state

Indicate an invalid selection by setting the `invalid` prop to `true`. Provide
feedback to users with the `invalidText` prop.

<Dropdown invalid invalidText="Secondary contact method must be different from the primary contact" titleText="Contact" selectedId="0" items="{[{id: "0", text: "Slack"},
  {id: "1", text: "Email"},
  {id: "2", text: "Fax"}]}" />

## Warning state

Indicate a warning state by setting the `warn` prop to `true`. Provide additional
context with the `warnText` prop.

<Dropdown warn warnText="This contact method is not associated with your account" titleText="Contact" selectedId="0" items="{[{id: "0", text: "Slack"},
  {id: "1", text: "Email"},
  {id: "2", text: "Fax"}]}" />

## Disabled state

Disable the entire dropdown by setting the `disabled` prop to `true`. This prevents
user interaction with the component.

<Dropdown disabled titleText="Contact" selectedId="0" items="{[{id: "0", text: "Slack"},
  {id: "1", text: "Email"},
  {id: "2", text: "Fax"}]}" />

## Disabled items

Disable specific items in the dropdown by setting the `disabled` property to
`true` in the item object. This allows for more granular control over available
selections.

<Dropdown
  selectedId="0"
  titleText="Contact"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email", disabled: true },
    { id: "2", text: "Fax" },
  ]}
/>

## Skeleton

Display a loading state using the `DropdownSkeleton` component. This provides
visual feedback while the dropdown content is being loaded.

<DropdownSkeleton />