Dropdown

A dropdown select component that allows users to choose one or multiple options from a list.

Features

• Single and multi-select modes
• Search/filter functionality
• Grouped options
• Custom option rendering
• Keyboard navigation
• Loading and disabled states
• Icons and avatars support
• Virtual scrolling for large lists

Usage

Web (React)

import { Dropdown } from '@cuppa/ui'

function MyComponent() {
  const [selected, setSelected] = useState('option1')

  const options = [
    { value: 'option1', label: 'Option 1' },
    { value: 'option2', label: 'Option 2' },
    { value: 'option3', label: 'Option 3' },
  ]

  return (
    <Dropdown
      label="Choose an option"
      value={selected}
      onChange={setSelected}
      options={options}
      placeholder="Select..."
    />
  )
}

iOS (SwiftUI)

import CuppaUI

struct MyView: View {
  @State private var selected = "option1"

  let options = [
    DropdownOption(value: "option1", label: "Option 1"),
    DropdownOption(value: "option2", label: "Option 2"),
    DropdownOption(value: "option3", label: "Option 3"),
  ]

  var body: some View {
    CuppaDropdown(
      label: "Choose an option",
      selection: $selected,
      options: options,
      placeholder: "Select..."
    )
  }
}

Android (Jetpack Compose)

import com.cuppa.ui.components.CuppaDropdown
import androidx.compose.runtime.*

@Composable
fun MyScreen() {
  var selected by remember { mutableStateOf("option1") }

  val options = listOf(
    DropdownOption("option1", "Option 1"),
    DropdownOption("option2", "Option 2"),
    DropdownOption("option3", "Option 3")
  )

  CuppaDropdown(
    label = "Choose an option",
    value = selected,
    onValueChange = { selected = it },
    options = options,
    placeholder = "Select..."
  )
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | label | string | - | Label text above dropdown | | value | string/array | - | Selected value(s) | | onChange | function | - | Callback when selection changes | | options | array | [] | List of options | | placeholder | string | 'Select...' | Placeholder text | | multiple | boolean | false | Allow multiple selections | | searchable | boolean | false | Enable search/filter | | disabled | boolean | false | Disable the dropdown | | loading | boolean | false | Show loading state | | error | string | - | Error message |

Examples

With Search

<Dropdown
  label="Country"
  options={countries}
  searchable
  placeholder="Search countries..."
  onChange={setCountry}
/>

Multi-Select

<Dropdown
  label="Select tags"
  options={tags}
  multiple
  value={selectedTags}
  onChange={setSelectedTags}
/>

Grouped Options

const groupedOptions = [
  {
    group: 'Fruits',
    options: [
      { value: 'apple', label: 'Apple' },
      { value: 'banana', label: 'Banana' },
    ],
  },
  {
    group: 'Vegetables',
    options: [
      { value: 'carrot', label: 'Carrot' },
      { value: 'lettuce', label: 'Lettuce' },
    ],
  },
]

<Dropdown
  label="Food"
  options={groupedOptions}
  onChange={setFood}
/>

With Icons

const options = [
  { value: 'home', label: 'Home', icon: <HomeIcon /> },
  { value: 'profile', label: 'Profile', icon: <UserIcon /> },
  { value: 'settings', label: 'Settings', icon: <SettingsIcon /> },
]

<Dropdown
  label="Navigate to"
  options={options}
  onChange={setPage}
/>

Accessibility

• Keyboard navigation (arrow keys, enter, escape)
• Screen reader support with ARIA labels
• Focus management
• Type-ahead search support
• Proper label associations

Best Practices

1. Keep option labels concise
2. Use search for 10+ options
3. Group related options
4. Show loading states for async data
5. Provide clear placeholder text
6. Handle empty states gracefully