QUI React2.6.3

Side Navigation

A hierarchical, vertical navigation element that is typically placed on the left or right side of a page or screen. It is used to display a navigational hierarchy with one to three levels.

import {QSideNavigation} from "@qui/react"

Examples

Showcase

The side navigation data model is very similar to our menu item interface. Refer to the API section for exact details.

Applications

Supply a React node to the topNode input to implement search logic. Also see: matchSorter.

Applications

Controlled

The component can be controlled or uncontrolled.

When you supply the onExpandedChange and expanded props, the component is controlled. Otherwise, the component is uncontrolled and the value is tracked internally.

Learn more about controlled and uncontrolled components in the related React Documentation.

Uncontrolled
Controlled
Applications
Applications

Collapsible Panel

Set collapsible to true to render a toggle button at the bottom of the side navigation. On collapse, the panel will shrink to show only the primary page-level icons.

API

Item

Name & DescriptionOption(s)Default
id
*
Unique identifier of the item
string
active
If true, the component will render a style indicating an active or selected state.
boolean
aria-label
aria-label applied to the item. Should be supplied when collapsed is true.
string
childListStyle
Supply additional styles to the element that wraps each nav item's children. If the property by the same name is supplied to the individual nav item, both will apply. Conflicting styles from the item will take precedence.
CSSProperties
disabled
When true, the menu item is disabled
boolean
false
expanded
If true and this item has child items, this node will be expanded initially.
boolean
items
Child items.
QSideNavigationItem[]
label
The menu item's primary message
ReactNode
render
Item renderer for overriding the default item
ReactElement
<button />
role
HTML role attribute applied to the menuitem element. Use this property to override the role of the menuitem.
string
'menuitem'
searchCriteria
Additional search criteria. Not rendered, but can be used during searches to match against items.
string[]
sectionTitle
A label that renders above the item's content. Best paired with separator 'top' to visually partition sections of the menu.
ReactNode
separator
Whether to render this item as a separator. If this property is supplied, all content is ignored.
boolean
startIcon
icon positioned before the label.
| LucideIcon
| ReactNode
startIconSize
The size of the startIcon. Some icons may not look right at the default size. Provide this input to fine-tune.
| 'xs'
| 's'
| 'm'
| 'l'
| 'xl'
| string
| number
Type
string
Description
Unique identifier of the item
Type
boolean
Description
If true, the component will render a style indicating an active or selected state.
Type
string
Description
aria-label applied to the item. Should be supplied when collapsed is true.
Type
CSSProperties
Description
Supply additional styles to the element that wraps each nav item's children. If the property by the same name is supplied to the individual nav item, both will apply. Conflicting styles from the item will take precedence.
Type
boolean
Default
false
Description
When true, the menu item is disabled
Type
boolean
Description
If true and this item has child items, this node will be expanded initially.
Type
QSideNavigationItem[]
Description
Child items.
Type
ReactNode
Description
The menu item's primary message
Type
ReactElement
Default
<button />
Description
Item renderer for overriding the default item
Type
string
Default
'menuitem'
Description
HTML role attribute applied to the menuitem element. Use this property to override the role of the menuitem.
Type
string[]
Description
Additional search criteria. Not rendered, but can be used during searches to match against items.
Type
ReactNode
Description
A label that renders above the item's content. Best paired with separator 'top' to visually partition sections of the menu.
Type
boolean
Description
Whether to render this item as a separator. If this property is supplied, all content is ignored.
Type
| LucideIcon
| ReactNode
Description
icon positioned before the label.
Type
| 'xs'
| 's'
| 'm'
| 'l'
| 'xl'
| string
| number
Description
The size of the startIcon. Some icons may not look right at the default size. Provide this input to fine-tune.

QSideNavigationProps

Name & DescriptionOption(s)Default
items
*
The side navigation item to render. Refer to the item for detailed type information.
QSideNavigationItem[]
activeId
Supply this property to manually set the active item. Each item's id property is checked against this value.
string
as
The component used for the root node. It can be a React component or element.
| ElementType
| ComponentType
'div'
childListStyle
Supply additional styles to the element that wraps this item's children. If the property by the same name is supplied to the parent q-side-navigation component, both will be applied. For conflicting properties, nav item styles will take precedence.
CSSProperties
{}
className
The className property of the Element interface gets and sets the value of the class attribute of the specified element.
string
collapsed
if true, the panel will collapse to 48px of width. In collapsed mode, only the top-level icons are shown.
boolean
false
collapsible
if true, the component can be collapsed or expanded. If false, the value of the collapsed property will be static.
boolean
false
defaultCollapsed
Default value of the collapsed state when uncontrolled.
boolean
defaultExpanded
Default expanded items.
string[]
disableScrollAdjustment
If the number of sidebar items is sufficiently large, the active sidebar item may not be scrolled into view on initial load. We account for this by scrolling it into view after the component has initialized. Set this property to false to disable this behavior.
boolean
false
expanded
Controlled expansion state for the component. Each entry in the list corresponds to an id of a side navigation item that is expanded. Note that each item's expanded property, if provided, will override this state.
string[]
fullHeight
If true, the side navigation panel will take up the full height of its parent container.
boolean
false
identifyItem
Override the default identifier used to uniquely identify an item.
  • item
    (
      item: QSideNavigationItem,
    ) => string
    levelPadding
    The left-padding of each nested child item. This number corresponds to pixels.
    number
    24
    onCollapsedChange
    Callback fired whenever the collapsed state changes.
    • collapsedThe updated collapsed state.
    • eventThe event that triggered the change.
      (
        collapsed: boolean,
        event: SyntheticEvent,
      ) => void
      onExpandedChange
      Callback fired whenever an item is expanded or collapsed.
      • updatedStateThe updated state.
      • eventThe DOM event that triggered this change, typically a click or keypress.
      • expandedWhether the item is expanded as a result of this change.
      • itemThe item being expanded or collapsed.
        (
          updatedState: string[],
          event: SyntheticEvent,
          expanded: boolean,
          item: QSideNavigationItem,
        ) => void
        render
        Item renderer for overriding the default item
        ReactElement
        <div />
        stickyTopContent
        if true, the top content will stay in view as the side navigation scrolls.
        boolean
        false
        style
        The style global attribute contains CSS styling declarations to be applied to the element.
        CSSProperties
        topNode
        Template content to render at the top of the side navigation, typically used for a search bar.
        ReactNode
        Type
        QSideNavigationItem[]
        Description
        The side navigation item to render. Refer to the item for detailed type information.
        Type
        string
        Description
        Supply this property to manually set the active item. Each item's id property is checked against this value.
        Type
        | ElementType
        | ComponentType
        Default
        'div'
        Description
        The component used for the root node. It can be a React component or element.
        Type
        CSSProperties
        Default
        {}
        Description
        Supply additional styles to the element that wraps this item's children. If the property by the same name is supplied to the parent q-side-navigation component, both will be applied. For conflicting properties, nav item styles will take precedence.
        Type
        string
        Description
        The className property of the Element interface gets and sets the value of the class attribute of the specified element.
        Type
        boolean
        Default
        false
        Description
        if true, the panel will collapse to 48px of width. In collapsed mode, only the top-level icons are shown.
        Type
        boolean
        Default
        false
        Description
        if true, the component can be collapsed or expanded. If false, the value of the collapsed property will be static.
        Type
        boolean
        Description
        Default value of the collapsed state when uncontrolled.
        Type
        string[]
        Description
        Default expanded items.
        Type
        boolean
        Default
        false
        Description
        If the number of sidebar items is sufficiently large, the active sidebar item may not be scrolled into view on initial load. We account for this by scrolling it into view after the component has initialized. Set this property to false to disable this behavior.
        Type
        string[]
        Description
        Controlled expansion state for the component. Each entry in the list corresponds to an id of a side navigation item that is expanded. Note that each item's expanded property, if provided, will override this state.
        Type
        boolean
        Default
        false
        Description
        If true, the side navigation panel will take up the full height of its parent container.
        Type
        (
          item: QSideNavigationItem,
        ) => string
        Description
        Override the default identifier used to uniquely identify an item.
        • item
          Type
          number
          Default
          24
          Description
          The left-padding of each nested child item. This number corresponds to pixels.
          Type
          (
            collapsed: boolean,
            event: SyntheticEvent,
          ) => void
          Description
          Callback fired whenever the collapsed state changes.
          • collapsedThe updated collapsed state.
          • eventThe event that triggered the change.
            Type
            (
              updatedState: string[],
              event: SyntheticEvent,
              expanded: boolean,
              item: QSideNavigationItem,
            ) => void
            Description
            Callback fired whenever an item is expanded or collapsed.
            • updatedStateThe updated state.
            • eventThe DOM event that triggered this change, typically a click or keypress.
            • expandedWhether the item is expanded as a result of this change.
            • itemThe item being expanded or collapsed.
              Type
              ReactElement
              Default
              <div />
              Description
              Item renderer for overriding the default item
              Type
              boolean
              Default
              false
              Description
              if true, the top content will stay in view as the side navigation scrolls.
              Type
              CSSProperties
              Description
              The style global attribute contains CSS styling declarations to be applied to the element.
              Type
              ReactNode
              Description
              Template content to render at the top of the side navigation, typically used for a search bar.
              Previous
              Radio
              Next
              Skeleton
              Examples
              Showcase
              Search
              Controlled
              Collapsible Panel
              API
              Item
              QSideNavigationProps
              Copyright © 2025 QUALCOMM incorporated. All rights reserved. This site is built using QUI Docs. Head over to the template repository to start building.