made for Nordcraft

Dropdown

A component that displays a button that opens a menu with a list of options when clicked. Implements the ARIA menu button pattern for proper accessibility support. The menu can contain various types of items including standard options, checkboxes, radio groups and nested submenus.

  • Can be controlled or uncontrolled

  • Supports submenus with configurable reading direction

  • Supports items, checkable items (single or multiple) with optional indeterminate state

  • Supports modal and non-modal modes

  • Customize side, alignment, offsets, collision handling

  • Optionally render a pointing arrow

  • Focus is fully managed

  • Full keyboard navigation

  • Typeahead support

  • Dismissing and layering behavior is highly customizable

Example

Architecture

zcore-dropdown-root
Slot: default
zcore-dropdown-trigger
Slot: default You must place an zcore-button here.
zcore-button
zcore-dropdown-portal
Slot: default
zcore-dropdown-content
Slot: default
zcore-dropdown-arrow
Slot: default
zcore-dropdown-scroll-area
Slot: default
zcore-dropdown-item
Slot: default
zcore-dropdown-link-item
Slot: default
zcore-dropdown-checkbox
Slot: default
zcore-dropdown-checkbox-indicator
Slot: default Place an element here that is rendered when checked.
Slot: indeterminate Place an element here that is rendered when indeterminate.
zcore-dropdown-radio-group
Slot: default
zcore-dropdown-radio-group-item
Slot: default
zcore-dropdown-radio-group-indicator
Slot: default
zcore-dropdown-sub
Slot: default
zcore-dropdown-sub-trigger
Slot: default You must place an zcore-dropdown-item here.
zcore-dropdown-item
Slot: default
zcore-dropdown-sub-portal
Slot: default
zcore-dropdown-sub-content
Slot: default You can place the same elements as in the zcore-dropdown-content here.

Reference

  • Root

    The root container that manages the state and behavior of the dropdown system. Coordinates the interaction between trigger and content components, handling events and state management for the entire dropdown hierarchy.

    • Attributes

      • default-open
        boolean
        /
        default: false

        The initial open state of the dropdown when rendered. Use when you do not need to control its open state.

      • direction
        enum
        /
        default: ltr

        The reading direction of the dropdown. Affects the positioning of submenus and keyboard navigation behavior.

      • modal
        boolean
        /
        default: true

        When true, interaction with elements outside the dropdown will be disabled and only dropdown content will be visible to screen readers.

      • open
        boolean
        /
        default: -

        The controlled open state of the dropdown. Must be used in conjunction with onOpenChange.

    • Events

      • onOpenChange

        Event handler called when the open state of the dropdown changes.

  • Trigger

    A wrapper component that must contain an zcore-button. The button controls the visibility of the dropdown content and automatically receives appropriate ARIA attributes for accessibility.

    • Portal

      Renders the dropdown content absolute or into the CSS top layer, ensuring proper stacking context and visibility above other page elements. This ensures consistent rendering and adequate layering of nested dropdowns.

      • Attributes

        • id
          string
          /
          default: -

          ID that is forwarded to the underlying container for DOM manipulation.

        • position
          enum
          /
          default: fixed

          Determines how the dropdown content will be placed on the page. Position fixed will prevent clipping, but will slightly lag on scroll events.

    • Content

      The container that holds the dropdown menu items. Manages keyboard interactions, focus behavior and positioning behavior. Implements proper ARIA attributes for accessibility and handles collision detection with viewport boundaries.

      • Attributes

        • align
          enum
          /
          default: start

          The preferred alignment against the trigger. May adjust automatically when collisions occur.

        • align-offset
          number
          /
          default: 0

          The offset in pixels from the start or end alignment positions.

        • aria-label
          string
          /
          default: -

          Accessible label for the dropdown content when a visible label is not present.

        • aria-labelled-by
          string
          /
          default: -

          References the ID of the element that labels the dropdown content.

        • arrow-padding
          number
          /
          default: 0

          The padding between the arrow and the edges of the content. Prevents arrow overflow with rounded corners.

        • avoid-collisions
          boolean
          /
          default: true

          When true, automatically adjusts positioning to prevent collisions with viewport boundaries.

        • collision-padding
          number
          /
          default: 0

          The distance in pixels from viewport edges where collision detection should occur.

        • id
          string
          /
          default: -

          ID that is forwarded to the underlying container for DOM manipulation.

        • loop
          boolean
          /
          default: false

          When true, keyboard navigation will loop from last item to first and vice versa.

        • match-anchor-width
          string
          /
          default: false

          If true, the content of the dropdown will have the same width as the dropdown anchor.

        • side
          enum
          /
          default: bottom

          The preferred side where the dropdown should appear relative to its trigger.

        • side-offset
          number
          /
          default: 0

          The distance in pixels between the dialog and its trigger element.

      • Events

        • onClickOutside

          Event handler called when a click occurs outside the dropdown content.

        • onCloseTransitionEnd

          Event handler called when the closing transition completes.

        • onEscapeKeydown

          Event handler called when the Escape key is pressed while the dropdown is active.

        • onOpenTransitionEnd

          Event handler called when the opening transition completes.

      • Classes

        • bottom

          Applied when the dropdown content is positioned at the bottom of the trigger.

        • bottom-in

          Applied when content is positioned at the bottom during the opening transition.

        • bottom-out

          Applied when content is positioned at the bottom during the closing transition.

        • close-transition

          Applied during the closing transition of the dropdown.

        • left

          Applied when the dropdown content is positioned to the left of the trigger.

        • left-in

          Applied when content is positioned on the left side during the opening transition.

        • left-out

          Applied when content is positioned on the left side during the closing transition.

        • open

          Applied when the dropdown is in an open state.

        • open-transition

          Applied during the opening transition of the dropdown.

        • right

          Applied when the dropdown content is positioned to the right of the trigger.

        • right-in

          Applied when content is positioned on the right side during the opening transition.

        • right-out

          Applied when content is positioned on the right side during the closing transition.

        • top

          Applied when the dropdown content is positioned at the top of the trigger.

        • top-in

          Applied when content is positioned at the top during the opening transition.

        • top-out

          Applied when content is positioned at the top during the closing transition.

    • Arrow

      An optional visual indicator that points to the trigger element. Must be rendered inside zcore-dropdown-content or zcore-dropdown-sub-content. Helps visually connect the submenu with its trigger element.

      • Attributes

        • id
          string
          /
          default: -

          ID that is forwarded to the underlying element for DOM manipulation.

      • Classes

        • bottom

          Applied when the arrow is positioned at the bottom of the content.

        • left

          Applied when the arrow is positioned on the left side of the content.

        • right

          Applied when the arrow is positioned on the right side of the content.

        • top

          Applied when the arrow is positioned at the top of the content.

    • Item

      A selectable item within the dropdown menu. Manages selection state and keyboard navigation while providing proper ARIA attributes for accessibility.

      • Attributes

        • disabled
          boolean
          /
          default: false

          When true, prevents the user from selecting this item.

        • id
          string
          /
          default: -

          ID that is forwarded to the underlying element for DOM manipulation.

        • text-value
          string
          /
          default: -

          Optional text used for typeahead purposes. By default, the typeahead behavior will use the content of the item. Use this when the content is complex, or you have non-textual content inside.

      • Events

        • onSelect

          Event handler called when the item is clicked or on keydown (Space / Enter).

      • Classes

        • disabled

          Applied when the item is in a disabled state.

        • open

          Applied when the item is used as a trigger and its assigned submenu is open.

    • Link item

      A selectable link item within the dropdown menu. Manages selection state and keyboard navigation while providing proper ARIA attributes for accessibility.

      • Attributes

        • disabled
          boolean
          /
          default: false

          When true, prevents the user from selecting this item.

        • download
          string
          /
          default: -

          Download attribute that is forwarded to the underlying a element.

        • href
          string
          /
          default: -

          Specifies the URL or destination that the link points to. For more information, see the MDN documentation.

        • id
          string
          /
          default: -

          ID that is forwarded to the underlying element for DOM manipulation.

        • prerender
          string
          /
          default: -

          Controls the prerendering behavior of the linked content. none disables prerendering, moderate provides balanced prerendering and eager prerenders as soon as possible. For more information see the Nordcraft documentation.

        • rel
          string
          /
          default: noopener noreferrer

          Specifies the relationship between the current document and the linked document. For security best practices and more information, see the MDN documentation.

        • target
          string
          /
          default: _blank

          Determines where the linked content will be displayed. For detailed information about target values and their behaviors, see the MDN documentation.

        • text-value
          string
          /
          default: -

          Optional text used for typeahead purposes. By default, the typeahead behavior will use the content of the item. Use this when the content is complex, or you have non-textual content inside.

      • Events

        • onSelect

          Event handler called when the item is clicked or on keydown (Space / Enter).

      • Classes

        • disabled

          Applied when the item is in a disabled state.

        • open

          Applied when the item is used as a trigger and its assigned submenu is open.

    • Checkbox item

      A menu item that can be checked, unchecked, or set to an indeterminate state. Implements proper ARIA attributes for accessibility and manages its selection state independently.

      • Attributes

        • checked
          boolean
          /
          default: -

          The controlled checked state of the item. Must be used in conjunction with onCheckedChange.

        • disabled
          boolean
          /
          default: false

          When true, prevents the user from interacting with this item.

        • id
          string
          /
          default: -

          ID that is forwarded to the underlying element for DOM manipulation.

        • text-value
          string
          /
          default: -

          Optional text used for typeahead purposes. By default, the typeahead behavior will use the content of the item.

      • Events

        • onCheckedChange

          Event handler called when the checked state of the item changes.

      • Classes

        • checked

          Applied when the item is in a checked state.

        • disabled

          Applied when the item is in a disabled state.

        • indeterminate

          Applied when the item is in an indeterminate state.

    • Checkbox indicator

      Visual indicator that displays when its parent checkbox item is checked or indeterminate. Can be styled directly or used as a wrapper for an icon to provide visual feedback of the item's state.

      • Classes

        • checked

          Applied when the parent checkbox item is in a checked state.

        • indeterminate

          Applied when the parent checkbox item is in an indeterminate state.

    • Radio group

      A container for grouping multiple radio items. Ensures that only one item in the group can be selected at a time, maintaining proper ARIA attributes for accessibility.

      • Attributes

        • value
          string
          /
          default: -

          The value of the currently selected radio item in the group. Must be used in conjunction with onValueChange.

      • Events

        • onValueChange

          Event handler called when the selected value in the radio group changes.

    • Radio group item

      A selectable item within a radio group that can only be selected exclusively within its group. Implements proper ARIA attributes for accessibility and manages its selection state within the group context.

      • Attributes

        • disabled
          boolean
          /
          default: false

          When true, prevents the user from selecting this item.

        • id
          string
          /
          default: -

          ID that is forwarded to the underlying element for DOM manipulation.

        • text-value
          string
          /
          default: -

          Optional text used for typeahead purposes. By default, the typeahead behavior will use the content of the item.

        • value
          string
          /
          default: -

          The unique value of the item. Used to identify the selected item within the radio group.

      • Events

        • onSelect

          Event handler called when the radio item is selected.

      • Classes

        • checked

          Applied when the radio item is in a selected state.

        • disabled

          Applied when the radio item is in a disabled state.

    • Radio group indicator

      Visual indicator that displays when its parent radio item is selected. Can be styled directly or used as a wrapper for an icon to provide visual feedback of the selection state.

      • Classes

        • checked

          Applied when the parent radio item is in a selected state.

    • Sub

      Container component that manages the state and behavior of a submenu. Coordinates the interaction between trigger and content components, enabling nested menu structures.

      • Attributes

        • default-open
          boolean
          /
          default: false

          The initial open state of the submenu when rendered. Use when you do not need to control its open state.

        • open
          boolean
          /
          default: -

          The controlled open state of the submenu. Must be used in conjunction with onOpenChange.

      • Events

        • onOpenChange

          Event handler called when the open state of the submenu changes.

    • Sub trigger

      A wrapper component that must contain an zcore-dropdown-item. Controls the visibility of its submenu and automatically receives appropriate ARIA attributes for accessibility.

      • Sub portal

        Renders the submenu content into the CSS top layer, ensuring proper stacking context and visibility above other page elements, including its parent dropdown.

        • Attributes

          • id
            string
            /
            default: -

            ID that is forwarded to the underlying container for DOM manipulation.

          • position
            enum
            /
            default: fixed

            Determines how the submenu content will be placed on the page. Position fixed will prevent clipping, but will slightly lag on scroll events.

      • Sub content

        The container that holds the submenu content. Manages keyboard interactions and positioning behavior while maintaining proper focus management within the submenu context.

        • Attributes

          • align
            enum
            /
            default: start

            The preferred alignment against the trigger. May adjust automatically when collisions occur.

          • align-offset
            number
            /
            default: 0

            The offset in pixels from the start or end alignment positions.

          • aria-label
            string
            /
            default: -

            Accessible label for the submenu content when a visible label is not present.

          • aria-labelled-by
            string
            /
            default: -

            References the ID of the element that labels the submenu content.

          • arrow-padding
            number
            /
            default: 0

            The padding between the arrow and the edges of the content. Prevents arrow overflow with rounded corners.

          • avoid-collisions
            boolean
            /
            default: true

            When true, automatically adjusts positioning to prevent collisions with viewport boundaries.

          • collision-padding
            number
            /
            default: 0

            The distance in pixels from viewport edges where collision detection should occur.

          • fallback-sides
            enum[]
            /
            default: -

            Alternative sides to try when the content doesn't fit in its primary position.

          • id
            string
            /
            default: -

            ID that is forwarded to the underlying container for DOM manipulation.

          • loop
            boolean
            /
            default: false

            When true, keyboard navigation will loop from last item to first and vice versa.

          • side-offset
            number
            /
            default: 0

            The distance in pixels between the submenu content and its trigger element.

        • Events

          • onClickOutside

            Event handler called when a click occurs outside the submenu content.

          • onCloseTransitionEnd

            Event handler called when the closing transition completes.

          • onEscapeKeydown

            Event handler called when the Escape key is pressed while the submenu is active.

          • onOpenTransitionEnd

            Event handler called when the opening transition completes.

        • Classes

          • bottom

            Applied when the dropdown sub content is positioned at the bottom of the trigger.

          • bottom-in

            Applied when content is positioned at the bottom during the opening transition.

          • bottom-out

            Applied when content is positioned at the bottom during the closing transition.

          • close-transition

            Applied during the closing transition of the sub content.

          • left

            Applied when the dropdown sub content is positioned to the left of the trigger.

          • left-in

            Applied when content is positioned on the left side during the opening transition.

          • left-out

            Applied when content is positioned on the left side during the closing transition.

          • open

            Applied when the dropdown sub content is in an open state.

          • open-transition

            Applied during the opening transition.

          • right

            Applied when the dropdown sub content is positioned to the right of the trigger.

          • right-in

            Applied when sub content is positioned on the right side during the opening transition.

          • right-out

            Applied when content is positioned on the right side during the closing transition.

          • top

            Applied when the dropdown sub content is positioned at the top of the trigger.

          • top-in

            Applied when content is positioned at the top during the opening transition.

          • top-out

            Applied when content is positioned at the top during the closing transition.

      • Scroll area

        A scrollable container that allows scrolling in a dropdown, which is in modal mode. All scrolling outside of this container will be prevented.

        • Attributes

          • id
            string
            /
            default: -

            ID that is forwarded to the underlying element.

      Keyboard

      • Space

        When focus is on the trigger, opens the dropdown. When focus is on a menu item, activates the item or toggles its checked state.

      • Enter

        When focus is on the trigger, opens the dropdown. When focus is on a menu item, activates the item or toggles its checked state.

      • When focus is on the trigger, opens the dropdown and moves focus to the first menu item. When focus is on a menu item, moves focus to the next menu item. When focus is on the last item, moves focus to the first item if loop is enabled.

      • When focus is on the trigger and the dropdown is open, moves focus to the last menu item. When focus is on a menu item, moves focus to the previous menu item. When focus is on the first item, moves focus to the last item if loop is enabled.

      • When focus is on a zcore-dropdown-sub-trigger, opens its submenu when direction is ltr, or closes it when direction is rtl.

      • When focus is on a zcore-dropdown-sub-trigger, closes its submenu when direction is ltr, or opens it when direction is rtl.

      • Escape

        Closes the dropdown and returns focus to the trigger element.