Navigation

NavigationItem

A single row within `Navigation`, used internally for recursive nesting.

html

<UiNavigationItem :item="..." :itemKey="..." />

Never mounted on its own

NavigationItem reads the active path, colour and variant it needs from a context Navigation provides — rendering one outside a Navigation throws. Every preview below is a real Navigation, with the prop being described pointed out in the text.

Item

required

item is one row of the tree: a title, an optional icon and badge, either a path to navigate to or a value to select, and children for the rows beneath it. It can also be a type: 'label' heading or a type: 'separator' rule instead of a link. Navigation renders one of these per entry and recurses through children.

Item key

required

itemKey is the path identifying this row within the tree — '0' for the first root, '0.1' for its second child. Navigation builds it as it recurses and uses it to track which parents are expanded, so a row's open state survives re-renders even when two siblings share a title.

Nested

nested marks a row as living inside another row's children rather than at the root. It's what indents the row and drops its icon gutter, so a child lines up under its parent's label instead of under the parent's icon — compare the top-level rows below with the ones under “Components”.

API Reference

Generated from the component's source — props, slots and emits as the component actually declares them.

Props

Prop

Type

Default

Description

itemrequired

NavigationItem

—

The navigation node data to render for this item.

itemKeyrequired

string

—

Unique key identifying this item within the navigation tree, used to track expansion state.

nested

boolean

false

Whether this item is rendered inside another item's `children`, rather than at the root of `navigation`. Set internally when recursing — a label's "no margin when first" treatment only applies at the root, since a nested label is never the first item of the whole navigation.

Types

type NavigationColor = "neutral" | "primary" | "secondary" | "success" | "error" | "warning" | "info" | "pending";

type NavigationVariant = "solid" | "subtle" | "soft" | "ghost";

interface NavigationItem {
    title: string;
    path?: string;
    value?: string;
    icon?: string;
    badge?: string | number;
    children?: NavigationItem[];
    defaultOpen?: boolean;
    /**
     * @defaultValue 'link'
     */
    type?: "link" | "label" | "separator";
}

interface NavigationContext {
    isExpanded: (key: string) => boolean;
    toggle: (key: string) => void;
    isActive: (item: NavigationItem) => boolean;
    select: (item: NavigationItem) => void;
    color: ComputedRef<NavigationColor>;
    badgeColor: ComputedRef<NavigationColor>;
    variant: ComputedRef<NavigationVariant>;
}