Crossbuild UI

Installation

$ cbui-cli install @crossbuildui/dropdown

To get started, please make sure you have installed cbui-cli globally and authenticated your account. This will ensure you can access all the necessary features.

View documents

Import

MyComponent.tsx

import {
    Dropdown,
    DropdownTrigger,
    DropdownMenu,
    DropdownItem,
    DropdownSection
} from '@/crossbuildui/dropdown';
import type { DropdownColor, DropdownSelectionMode, DropdownVariant } from '@/crossbuildui/dropdown'; // Optional
import { Button } from '@/crossbuildui/button'; // Or your preferred trigger

Dependencies

The default selected icon in DropdownItem uses react-native-vector-icons/MaterialIcons. Ensure this library is installed and linked if you rely on the default icon. You can provide your own custom selectedIcon to avoid this dependency.

Composition

The Dropdown system is built with a composable API, requiring specific child components:

Dropdown: The main wrapper component that orchestrates the behavior and state. It expects exactly two children: DropdownTrigger and DropdownMenu.
DropdownTrigger: Wraps the element (e.g., a Button) that toggles the dropdown menu's visibility.
DropdownMenu: Contains the list of options. It can host DropdownItem and DropdownSection components as children, or render dynamic items from an items prop.
DropdownItem: Represents an individual selectable option within the menu.
DropdownSection: Allows grouping of DropdownItems with an optional title and divider.

Context API

The Dropdown components heavily utilize the React Context API (DropdownContext) to share state (like isOpen, selectedKeys) and props (like variant, color, theme information) between the main Dropdown, DropdownMenu, and its descendants (DropdownItem, DropdownSection).

Basic Usage

A minimal dropdown consists of a trigger and a menu with items. The menu appears in a modal.

MyComponent.tsx

function App() {
  const [selectedKey, setSelectedKey] = useState<string | null>(null);

  return (
    <Dropdown>
      <DropdownTrigger>
        <CrossBuildButton>{selectedKey ? `Selected: ${selectedKey}` : "Open Menu"}</CrossBuildButton>
      </DropdownTrigger>
      <DropdownMenu
        aria-label="Actions"
        selectionMode="single"
        selectedKeys={selectedKey ? [selectedKey] : []}
        onSelectionChange={(keys) => setSelectedKey(Array.from(keys)[0] as string)}
      >
        <DropdownItem itemKey="edit">Edit File</DropdownItem>
        <DropdownItem itemKey="duplicate">Duplicate File</DropdownItem>
        <DropdownItem itemKey="delete" color="danger">Delete File</DropdownItem>
      </DropdownMenu>
    </Dropdown>
  );
}

Selection Modes

The DropdownMenu supports different selection behaviors via the selectionMode prop:

none (default): Items are not selectable; they act as simple actions.
single: Only one item can be selected at a time.
multiple: Multiple items can be selected.

Use selectedKeys (controlled) or defaultSelectedKeys (uncontrolled) and onSelectionChange to manage selection. The disallowEmptySelection prop (boolean) can prevent deselection if it would result in no items being selected (relevant for single and multiple modes). The closeOnSelect prop (boolean, defaults to true) on DropdownMenu determines if the menu closes after an item is selected.

MyComponent.tsx

function App() {
  const [singleSelected, setSingleSelected] = useState(new Set(['cat']));
  const [multipleSelected, setMultipleSelected] = useState(new Set(['lion', 'tiger']));

  return (
    <View style={{ gap: 20 }}>
      <View>
        <Text style={{ marginBottom: 5 }}>Single Selection (selected: {Array.from(singleSelected).join(", ")})</Text>
        <Dropdown>
          <DropdownTrigger><CrossBuildButton>Select Animal</CrossBuildButton></DropdownTrigger>
          <DropdownMenu
            aria-label="Single selection example"
            selectionMode="single"
            selectedKeys={singleSelected}
            onSelectionChange={setSingleSelected}
            disallowEmptySelection // Example: must select one
          >
            <DropdownItem itemKey="dog">Dog</DropdownItem>
            <DropdownItem itemKey="cat">Cat</DropdownItem>
            <DropdownItem itemKey="mouse">Mouse</DropdownItem>
          </DropdownMenu>
        </Dropdown>
      </View>

      <View>
        <Text style={{ marginBottom: 5 }}>Multiple Selection (selected: {Array.from(multipleSelected).join(", ")})</Text>
        <Dropdown>
          <DropdownTrigger><CrossBuildButton>Select Animals</CrossBuildButton></DropdownTrigger>
          <DropdownMenu
            aria-label="Multiple selection example"
            selectionMode="multiple"
            selectedKeys={multipleSelected}
            onSelectionChange={setMultipleSelected}
            closeOnSelect={false} // Keep menu open for multiple selections
          >
            <DropdownItem itemKey="lion">Lion</DropdownItem>
            <DropdownItem itemKey="tiger">Tiger</DropdownItem>
            <DropdownItem itemKey="bear">Bear</DropdownItem>
            <DropdownItem itemKey="snake" isDisabled>Snake (Disabled)</DropdownItem>
          </DropdownMenu>
        </Dropdown>
      </View>
    </View>
  );
}

Sections

Group related items using DropdownSection. It can have a title and an optional showDivider prop. Section-specific itemStyle and hideSelectedIcon can also be applied.

MyComponent.tsx

function App() {
  return (
    <Dropdown>
      <DropdownTrigger><CrossBuildButton>Actions</CrossBuildButton></DropdownTrigger>
      <DropdownMenu aria-label="Actions with sections">
        <DropdownSection title="File Operations" itemKey="s1">
          <DropdownItem itemKey="new">New File</DropdownItem>
          <DropdownItem itemKey="copy">Copy Link</DropdownItem>
        </DropdownSection>
        <DropdownSection title="Danger Zone" showDivider itemKey="s2">
          <DropdownItem itemKey="delete" color="danger">Delete File</DropdownItem>
        </DropdownSection>
      </DropdownMenu>
    </Dropdown>
  );
}

Dynamic Items

Render items dynamically by passing an array to the items prop of DropdownMenu and providing a render function as its child or via the renderItem prop.

MyComponent.tsx

const fileOptions = [
  { id: 'doc1', name: 'Document A.pdf', type: 'file' },
  { id: 'img1', name: 'Image X.png', type: 'image', disabled: true },
  { id: 'vid1', name: 'Video Y.mp4', type: 'video' },
];

function App() {
  return (
    <Dropdown>
      <DropdownTrigger><CrossBuildButton>Open Dynamic Menu</CrossBuildButton></DropdownTrigger>
      <DropdownMenu
        aria-label="Dynamic items"
        items={fileOptions}
        onSelectionChange={(keys) => console.log('Selected:', keys)}
      >
        {(item) => (
          <DropdownItem
            itemKey={item.id}
            title={item.name}
            description={`Type: ${item.type}`}
            isDisabled={item.disabled}
            startContent={<Text>{item.type === 'file' ? '📄' : item.type === 'image' ? '🖼️' : '🎞️'}</Text>}
          />
        )}
      </DropdownMenu>
    </Dropdown>
  );
}

Menu Variants & Colors

The DropdownMenu supports several visual styles through the variant prop (solid, bordered, light, flat, faded, shadow) and thematic coloring via the color prop (default, primary, etc.).

MyComponent.tsx

const variants: DropdownVariant[] = ['solid', 'bordered', 'light', 'flat', 'faded', 'shadow'];
const colors: DropdownColor[] = ['default', 'primary', 'secondary', 'success', 'warning', 'danger'];

function App() {
  return (
    <View style={{ flexDirection: 'row', flexWrap: 'wrap', gap: 16 }}>
      {variants.map(variant => (
        colors.map(color => (
          <Dropdown key={`${variant}-${color}`}>
            <DropdownTrigger>
              <CrossBuildButton size="sm" style={{ paddingHorizontal: 8, paddingVertical: 4 }}>
                {variant} - {color}
              </CrossBuildButton>
            </DropdownTrigger>
            <DropdownMenu variant={variant} color={color} aria-label={`${variant} ${color} menu`}>
              <DropdownItem itemKey="action1">Action 1</DropdownItem>
              <DropdownItem itemKey="action2">Action 2</DropdownItem>
            </DropdownMenu>
          </Dropdown>
        ))
      ))}
    </View>
  );
}

Custom Item Content

DropdownItem offers props like description, startContent, and endContent to enrich item appearance. The selectedIcon prop allows for custom selection indicators. If hideSelectedIcon is true (can be set on Menu, Section, or Item), the icon is hidden.

MyComponent.tsx

function App() {
  return (
    <Dropdown>
      <DropdownTrigger><CrossBuildButton>User Profile</CrossBuildButton></DropdownTrigger>
      <DropdownMenu aria-label="User actions">
        <DropdownItem
          itemKey="profile"
          title="Signed in as"
          description="zoey@example.com"
          textValue="User Profile Zoey" // For accessibility
          startContent={<View style={{ width: 24, height: 24, borderRadius: 12, backgroundColor: 'skyblue' }} />}
        />
        <DropdownItem itemKey="settings" startContent={<Text>⚙️</Text>}>Settings</DropdownItem>
        <DropdownItem itemKey="logout" color="danger" endContent={<Text>➡️</Text>}>
          Log Out
        </DropdownItem>
      </DropdownMenu>
    </Dropdown>
  );
}

Menu Customization

DropdownMenu provides props for further customization:

topContent / bottomContent: Add custom React nodes at the top or bottom of the menu list.
emptyContent: Display custom content when there are no items to show.
disableAnimation: Disable the default fade animation of the modal.
disabledKeys: An iterable of item keys that should be disabled.

MyComponent.tsx

function App() {
  return (
    <Dropdown>
      <DropdownTrigger><CrossBuildButton>Menu Features</CrossBuildButton></DropdownTrigger>
      <DropdownMenu
        aria-label="Customized menu"
        topContent={<View style={{ padding: 10, borderBottomWidth: 1, borderColor: '#eee' }}><Text>Header Content</Text></View>}
        bottomContent={<View style={{ padding: 10, borderTopWidth: 1, borderColor: '#eee' }}><Text>Footer Content</Text></View>}
        emptyContent={<View style={{ padding: 20 }}><Text>Nothing to show here!</Text></View>}
        // items={[]} // To show emptyContent
        disableAnimation
        closeOnSelect={false}
      >
        <DropdownItem itemKey="one">Option One (stays open)</DropdownItem>
        <DropdownItem itemKey="two">Option Two</DropdownItem>
      </DropdownMenu>
    </Dropdown>
  );
}

Props Overview

Dropdown Props

PROP	TYPE	DESCRIPTION
`children`	`[Trigger, Menu]`	Must be `DropdownTrigger` followed by `DropdownMenu`.

DropdownTrigger Props

PROP	TYPE	DESCRIPTION
`children`	`ReactNode`	The trigger element (e.g., Button).
`style`	`StyleProp<ViewStyle>`	Style for the trigger wrapper View.

DropdownMenu Props

PROP	TYPE	DEFAULT	DESCRIPTION
`children`	`ReactNode \| (item) => Element`	-	Static items or render function for dynamic items.
`items`	`T[]`	-	Array of data for dynamic rendering.
`renderItem`	`(item: T) => Element`	-	Render function for dynamic items if children is not a function.
`variant`	`DropdownVariant`	`'solid'`	Visual style of the menu.
`color`	`DropdownColor`	`'default'`	Thematic color of the menu.
`selectionMode`	`DropdownSelectionMode`	`'none'`	Selection behavior.
`selectedKeys`	`Iterable<string\|number>`	-	Controlled selected item keys.
`defaultSelectedKeys`	`Iterable<string\|number>`	`[]`	Uncontrolled initial selected keys.
`disabledKeys`	`Iterable<string\|number>`	`[]`	Keys of items to disable.
`disallowEmptySelection`	`boolean`	`false`	Prevent deselection to an empty state.
`topContent`	`ReactNode`	-	Content to display above the items.
`bottomContent`	`ReactNode`	-	Content to display below the items.
`emptyContent`	`ReactNode`	Default Text	Content when no items are available.
`hideSelectedIcon`	`boolean`	`false`	Hide selection indicator for all items in this menu.
`closeOnSelect`	`boolean`	Context-based (true)	Whether to close the menu on item selection.
`disableAnimation`	`boolean`	`false`	Disable menu open/close animation.
`style`	`StyleProp<ViewStyle>`	-	Style for the menu container.
`itemStyle`	`Partial<DropdownItemSlots>`	-	Default styles for direct child item slots.
`onSelectionChange`	`(keys: Set) => void`	-	Callback when selection changes.

DropdownItem Props

PROP	TYPE	DEFAULT	DESCRIPTION
`children`	`ReactNode`	-	Primary content, overrides title.
`itemKey`	`string \| number`	Required	Unique key for the item.
`title`	`ReactNode`	-	Title of the item if children not provided.
`textValue`	`string`	-	Plain text for accessibility/typeahead.
`description`	`ReactNode`	-	Additional descriptive text.
`startContent`	`ReactNode`	-	Content to render before the title/description.
`endContent`	`ReactNode`	-	Content to render after the selected icon.
`selectedIcon`	`ReactNode \| (props) => Node`	Default Check Icon	Custom selection indicator.
`showDivider`	`boolean`	`false`	Show a divider after this item.
`hideSelectedIcon`	`boolean`	Context-based	Override menu/section setting for this item.
`style`	`StyleProp<ViewStyle>`	-	Style for the item's outer Pressable.
`slotStyles`	`Partial<DropdownItemSlots>`	-	Styles for inner parts of the item.
`isDisabled`	`boolean`	`false`	Explicitly disable this item.

DropdownSection Props

PROP	TYPE	DEFAULT	DESCRIPTION
`children`	`ReactNode`	Required	DropdownItems within this section.
`itemKey`	`string \| number`	Required	Unique key for the section.
`title`	`string`	-	Title for the section.
`hideSelectedIcon`	`boolean`	Context-based	Override menu setting for items in this section.
`showDivider`	`boolean`	`false`	Show a divider after the section.
`dividerProps`	`StyleProp<ViewStyle>`	-	Style for the section divider.
`style`	`StyleProp<ViewStyle>`	-	Style for the section wrapper.
`itemStyle`	`Partial<DropdownItemSlots>`	-	Default styles for item slots in this section.

Styling

The Dropdown components offer various styling capabilities:

DropdownTrigger: Accepts a style prop for its wrapper View.
DropdownMenu: The style prop targets the main menu container. The variant and color props apply predefined visual styles. The itemStyle prop allows defining default styles for all DropdownItemSlots within this menu (can be overridden by Section or Item).
DropdownSection: The style prop targets the section's wrapper View. The itemStyle prop sets default styles for DropdownItemSlots within this section (overrides Menu, can be overridden by Item).dividerProps styles the optional divider.
DropdownItem: The style prop targets the outer Pressable component. The slotStyles prop provides granular styling for internal parts like base, wrapper, title, description, etc. (see DropdownItemSlots type).

Style Precedence

For DropdownItem styling, the precedence is:
1. Direct slotStyles on DropdownItem.
2. itemStyle from parent DropdownSection.
3. itemStyle from parent DropdownMenu.
4. Default styles within DropdownItem.
The style prop on DropdownItem always applies to its root Pressable.

MyComponent.tsx

function App() {
  return (
    <Dropdown>
      <DropdownTrigger style={{ borderWidth: 1, borderColor: 'blue', padding: 5, borderRadius: 6 }}>
        <CrossBuildButton variant="ghost">Styled Trigger</CrossBuildButton>
      </DropdownTrigger>
      <DropdownMenu
        aria-label="Styled Menu"
        style={{ borderColor: 'green', borderWidth: 2, borderRadius: 12 }} // Menu container style
        itemStyle={{ // Default item styles for this menu
          base: { paddingVertical: 15 },
          title: { fontWeight: 'bold', color: 'purple' },
        }}
      >
        <DropdownItem itemKey="custom" title="Custom Item Style" slotStyles={{
          wrapper: { backgroundColor: 'lightyellow' },
          description: { fontStyle: 'italic', color: 'orange' }
        }} description="This item has specific slot styles." />
        <DropdownSection itemKey="s1" title="Styled Section" style={{ backgroundColor: '#f0f0f0', marginTop: 5 }} itemStyle={{
          base: { borderLeftWidth: 3, borderLeftColor: 'red' }
        }}>
          <DropdownItem itemKey="sectioned">Item in Styled Section</DropdownItem>
        </DropdownSection>
      </DropdownMenu>
    </Dropdown>
  );
}

Installation

Import

Dropdown Components

Composition

Basic Usage

Selection Modes

Sections

Dynamic Items

Menu Variants & Colors

Custom Item Content

Menu Customization

Props Overview

Dropdown Props

DropdownTrigger Props

DropdownMenu Props

DropdownItem Props

DropdownSection Props

Styling

Accessibility