made for Nordcraft

Menubar

A visually persistent menu common in desktop applications that provides quick access to a consistent set of commands. Implements the ARIA menubar pattern for proper accessibility support.

  • Can be controlled or uncontrolled

  • Supports submenus with configurable reading direction

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

  • Customize side, alignment, offsets, collision handling

  • Optionally render a pointing arrow

  • Focus is fully managed

  • Full keyboard navigation

  • Typeahead support

Example

Architecture

zcore-menubar-root
Slot: default
zcore-menubar-menu
Slot: default
zcore-menubar-trigger
Slot: default You must place an zcore-button here.
zcore-button
zcore-menubar-portal
Slot: default
zcore-menubar-content
Slot: default
zcore-menubar-arrow
Slot: default
zcore-menubar-item
Slot: default
zcore-menubar-link-item
Slot: default
zcore-menubar-checkbox
Slot: default
zcore-menubar-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-menubar-radio-group
Slot: default
zcore-menubar-radio-group-item
Slot: default
zcore-menubar-radio-group-indicator
Slot: default
zcore-menubar-sub
Slot: default
zcore-menubar-sub-trigger
Slot: default You must place an zcore-menubar-item here.
zcore-menubar-item
Slot: default
zcore-menubar-sub-portal
Slot: default
zcore-menubar-sub-content
Slot: default You can place the same elements as in the zcore-menubar-content here.

Reference

  • Root

    The root container that manages the state and behavior of the menubar system. Coordinates the interaction between triggers and menu items while maintaining proper ARIA attributes for accessibility.

    • Attributes

      • default-value
        string
        /
        default: -

        The initial active menu when the menubar is rendered. Use when you do not need to control the active menu state.

      • direction
        enum
        /
        default: ltr

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

      • loop
        boolean
        /
        default: false

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

      • value
        string
        /
        default: -

        The controlled active menu state. Must be used in conjunction with onValueChange.

    • Events

      • onValueChange

        Event handler called when the active menu changes.

  • Menu

    The container for a menu. Handles the opening state of its content via its trigger.

    • Attributes

      • value
        string
        /
        default: -

        The unique id of the menu. Determines if the menu is open.

  • Trigger

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

    • Portal

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

      • Attributes

        • id
          string
          /
          default: -

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

    • Content

      The container that holds the 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 menu content when a visible label is not present.

        • aria-labelled-by
          string
          /
          default: -

          References the ID of the element that labels the menu 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: true

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

        • side
          enum
          /
          default: bottom

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

        • side-offset
          number
          /
          default: 0

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

      • Events

        • onClickOutside

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

        • onCloseTransitionEnd

          Event handler called when the closing transition completes.

        • onEscapeKeydown

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

        • onOpenTransitionEnd

          Event handler called when the opening transition completes.

      • Classes

        • bottom

          Applied when the menu 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 menu.

        • left

          Applied when the menu 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 menu is in an open state.

        • open-transition

          Applied during the opening transition of the menu.

        • right

          Applied when the menu 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 menu 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-menubar-content or zcore-menubar-sub-content. Helps visually connect the menu 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 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 activated via keyboard (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 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

        • indeterminate

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

        • open

          Applied when the parent checkbox item is in a checked 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 appropriate 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-menubar-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 menu.

        • Attributes

          • id
            string
            /
            default: -

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

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

          • left

            Applied when the submenu 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 submenu is in an open state.

          • open-transition

            Applied during the opening transition of the submenu.

          • right

            Applied when the submenu 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 submenu 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.

      Keyboard

      • Space

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

      • Enter

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

      • Moves focus to the next menu item. When focus is on the last item, moves focus to the first item if loop is enabled.

      • 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-menubar-sub-trigger, opens its submenu when direction is ltr, or closes it when direction is rtl.

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

      • Escape

        Closes the active menu and returns focus to its trigger element.