made for Nordcraft

Select

A flexible component that allows users to select a value from a list of options. Implements the ARIA listbox pattern for proper accessibility support.

  • Can be controlled or uncontrolled

  • Full focus management

  • Typeahead support

  • Full keyboard navigation

  • Supports Right to Left direction

Example

Architecture

zcore-select-root
Slot: default
zcore-select-trigger
Slot: default You need to place an zcore-button here.
zcore-button
Slot: default
zcore-select-icon
zcore-select-portal
Slot: default
zcore-select-backdrop
zcore-select-content
Slot: default Place your content here if you don't need scroll.
zcore-select-arrow
Slot: default You can place an arrow here.
zcore-select-item
Slot: default
zcore-select-item-indicator
Slot: default
zcore-select-item-text
Slot: default
zcore-select-scroll-area
Slot: default Place your content here if you need scroll.

Reference

  • Root

    The root container that manages the select's state and behavior. Coordinates the interaction between trigger, content, and optional backdrop components.

    • Attributes

      • default-open
        boolean
        /
        default: false

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

      • default-value
        any
        /
        default: -

        The initial selected value when the select is rendered. Use when you do not need to control the selected value.

      • direction
        enum
        /
        default: ltr

        The reading direction of the select component. Affects the positioning of the content and arrow.

      • disabled
        boolean
        /
        default: false

        When true, prevents the user from interacting with the select.

      • name
        string
        /
        default: -

        The name of the select when used within a form. Submitted with its owning form as part of a name/value pair.

      • open
        boolean
        /
        default: false

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

      • required
        boolean
        /
        default: false

        When true, indicates that a value must be selected before the owning form can be submitted.

      • type
        enum
        /
        default: single

        Defines if the selects acts as a single-select or a multi-select.

      • value
        any
        /
        default: -

        The controlled value of the select. Must be used in conjunction with onValueChange. If type is set to "multiple", it expects an array.

    • Events

      • onFocusChange

        Event handler called when the currently focused item changes. Includes the value of the item.

      • onOpenChange

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

      • onValueChange

        Event handler called when the selected value changes. Use the "value" key if type is "single", otherwise use the "values" key.

  • Trigger

    A wrapper component that must contain an zcore-button. The button controls the visibility of the select content. By default, the content positions itself relative to this trigger.

    • Icon

      A visual indicator typically used to show the current state of the select. Usually displayed as a chevron or arrow.

      • Classes

        • open

          Applied when the select is in an open state.

    • Portal

      Renders the select backdrop and content. If position is set to fixed, the content is placed in the CSS top layer, ensuring proper stacking context and visibility above other page elements.

      • Attributes

        • id
          string
          /
          default: -

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

        • position
          enum
          /
          default: absolute

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

    • Backdrop

      An optional overlay that renders behind the select content. Typically used to enhance focus on the select options.

      • Attributes

        • id
          string
          /
          default: -

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

      • Classes

        • close-transition

          Applied during the closing transition and removed when fully closed.

        • open

          Applied when the select is in an open state.

        • open-transition

          Applied during the opening transition and removed when fully open.

    • Content

      The container that holds the select options. Manages keyboard interactions and positioning behavior.

      • Attributes

        • align
          enum
          /
          default: center

          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 select content container.

        • aria-labelled-by
          string
          /
          default: -

          References the ID of the element that labels the select 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.

        • close-autofocus
          boolean
          /
          default: true

          When true, returns focus to the trigger element after the select closes.

        • 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.

        • hide-when-detached
          boolean
          /
          default: false

          When true, hides the content when the trigger element becomes fully obscured.

        • id
          string
          /
          default: -

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

        • match-anchor-width
          boolean
          /
          default: false

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

        • side
          enum
          /
          default: bottom

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

        • side-offset
          number
          /
          default: 0

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

        • sticky
          enum
          /
          default: partial

          Controls how the content stays within bounds. partial requires the trigger to be partially visible, while always keeps content in bounds regardless.

        • update-position-strategy
          enum
          /
          default: optimized

          Determines how often position updates occur. Use always sparingly as it updates on every animation frame.

      • Events

        • onClickOutside

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

        • onCloseTransitionEnd

          Event handler called when the closing transition completes.

        • onEscapeKeydown

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

        • onOpenTransitionEnd

          Event handler called when the opening transition completes.

      • Classes

        • bottom

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

        • bottom-in

          Applied when content is positioned at the bottom during opening.

        • bottom-out

          Applied when content is positioned at the bottom during closing.

        • close-transition

          Applied during the closing transition.

        • left

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

        • left-in

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

        • left-out

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

        • open

          Applied when the select is in an open state.

        • open-transition

          Applied during the opening transition.

        • right

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

        • right-in

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

        • right-out

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

        • top

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

        • top-in

          Applied when content is positioned at the top during opening.

        • top-out

          Applied when content is positioned at the top during closing.

    • Arrow

      An optional visual indicator that points to the trigger element. Must be rendered inside zcore-select-content.

      • 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 option within the select content. Manages selection state and keyboard navigation.

      • 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. When not provided, the item's content will be used.

        • value
          string
          /
          default: -

          The value associated with this item. This value will be submitted when used within a form.

      • Events

        • onSelect

          Is triggered when the select item is clicked or when it detects a Space or Enter keydown event.

    • Item indicator

      A visual indicator that shows when an item is selected. Typically rendered as a checkmark or similar icon.

      • Item text

        The textual content of a select item. Used for typeahead functionality and screen readers.

        • Scroll area

          A scrollable container that allows scrolling in a select, 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 trigger is focused, opens the select. When an item is focused, selects it and closes the select.

        • Enter

          When trigger is focused, opens the select. When an item is focused, selects it and closes the select.

        • Opens the select when trigger is focused and focuses the first item. Moves focus to the next item in the list. If focus is on the last item, moves focus to the first item.

        • Opens the select when trigger is focused and focuses the last item. Moves focus to the previous item in the list. If focus is on the first item, moves focus to the last item.

        • Escape

          Closes the select and returns focus to the trigger element.