Side Menu - BEEQ Design System

The side menu is a vertical navigation element that sits alongside a page or application layout. It acts as a central hub for accessing sections, features, and functionality.

Use bq-side-menu-item inside bq-side-menu; side menu items rely on the parent menu to manage collapsed and selected states.

When to use

Use side menus when

A website or application has extensive content or multiple hierarchical levels
A compact and organized navigation system is necessary
Users need persistent access to primary sections while they work

Do not use side menus when

The menu reduces the visibility of primary content
The interface is focused on reading or content consumption
The layout is too narrow to support persistent navigation

Patterns

Default view

Navigation items remain visible while users scroll. This gives people a persistent representation of the product structure.

Collapsible view

The collapsible view reduces the menu to a compact rail. Use it when space is constrained or when users need more room for content.

For grid sizes M to XS, applicable to viewports of 768 pixels and below, display the side menu in collapsed mode.

Anatomy

A side menu is composed of a container, selected item state, navigation items, and optional logo and footer areas.

Part	Element	Description
1	Container	The root `<aside>` surface that holds the side menu
2	Selected	The active item that represents the current location
3	Navigation item	A selectable `bq-side-menu-item` with optional prefix and suffix content
4	Logo and footer slots	Optional areas for brand content and supplementary actions

Design guidelines

Usage

Default

The default side menu is a versatile container for organizing and displaying navigation elements. Use it as the foundation for structured and intuitive navigation layouts. bq-side-menu-item is a child component, not a standalone navigation pattern. Use it only inside bq-side-menu. Within a side menu, items support default, active, hover, focus, disabled, and with-counter states.

Options

Appearance

Use the appearance attribute to align the side menu with your application’s visual language.

Default

The default appearance is a neutral style that works well in most contexts. It pairs with a light or dark background and uses color accents for active and hover states.

Brand

The brand appearance highlight the brand color as the background of the side menu. This creates a strong visual presence and reinforces brand identity.

Inverse

The inverse appearance is designed for use as the opposite of the BEEQ mode of the application. For example, if your app uses bq-mode="light", the inverse side menu will use the dark appearance, and vice versa.

Size

The side menu supports two sizes: medium (default) and small. The small size is a version of the side menu that shows only icons, hiding the text labels. Use the size attribute/property to switch between the two sizes.

When using the medium size, there’s no need to specify the size attribute, as it is the default. Default values are not required to be set explicitly, but you can add size="medium" for clarity if desired.

Use the footer slot for supplementary actions, links, or information at the bottom of the menu.

Collapse

Use collapse to create a compact side menu. Collapsed menus show icons and hide labels, but the logo can be customized to show or hide based on the collapsed state. The menu items will display their label content in a tooltip on hover when the menu is collapsed. Wire your app control to the side menu state so the button can expand and collapse the menu. Keep the icon-only button label in sync with the current state.

Best practices

DoChoose navigation titles that clearly communicate where each item leads.

Don’tAvoid arbitrary titles that hide the destination or force people to guess.

DoKeep navigation labels concise by removing words that do not add meaning.

Don’tAvoid long labels that wrap, truncate poorly, or reduce scanability.

DoUse sentence case for navigation items so labels read naturally.

Don’tAvoid title case or all caps when they make navigation harder to scan.

DoValidate icon meaning with users when icons are needed for collapsed navigation.

Don’tDo not rely on icons alone unless the destination remains understandable.

Accessibility

The side menu renders its root surface as an <aside> and places menu items inside a <nav>. Each bq-side-menu-item renders as a focusable button with role="menuitem", and the disabled property maps to aria-disabled="true" and tabindex="-1".

Landmark context - include semantic heading text in the logo slot to communicate the menu purpose and where its content begins.
Collapsed state - communicate the expanded or collapsed state through the surrounding layout control when you add one.
Icons - validate icon meaning when collapsed navigation relies on icons to identify destinations.
Labels - use unique labels that make sense without additional context. The item text feeds the collapsed tooltip content.
Keyboard navigation - side menu items support focus, click, Enter, and Space interaction through the underlying button.

API reference

Properties

Property	Attribute	Description	Type	Default
`appearance`	`appearance`	Sets a predefined appearance of the side menu	`'brand'` \| `'default'` \| `'inverse'`	`'default'`
`collapse`	`collapse`	If `true`, the container will reduce its width	`boolean`	`false`
`size`	`size`	Sets the size of the navigation menu items	`'medium'` \| `'small'`	`'medium'`

Property	Attribute	Description	Type	Default
`active`	`active`	If `true`, the menu item will be shown as active or selected	`boolean`	`false`
`collapse`	`collapse`	If `true`, the item label and suffix will be hidden and the width will be reduced according to its parent	`boolean`	`false`
`disabled`	`disabled`	If `true`, the menu item will be disabled and no interaction is allowed	`boolean`	`false`

Slots

Slot	Description
(default)	The main section that holds all menu items
`footer`	The section for adding footer content to the side menu
`logo`	The section for displaying the logo or brand in the side menu

Slot	Description
(default)	The content of the menu item
`prefix`	The prefix part of the menu item
`suffix`	The suffix part of the menu item

Shadow parts

Part	Description
`base`	HTML `<aside>` root container
`footer`	HTML `<div>` element that holds the footer
`logo`	HTML `<div>` element that holds the logo
`nav`	HTML `<nav>` element that holds the navigation items

Part	Description
`base`	The component wrapper container inside the shadow DOM
`label`	The label slot
`panel`	The `<div>` container that holds the tooltip content when the side menu is collapsed
`prefix`	The prefix slot
`suffix`	The suffix slot
`trigger`	The `<div>` container that holds the element that displays the tooltip on hover when the side menu is collapsed

Events

Event	Description	Type
`bqCollapse`	Fires when the side menu changes its width from expanded to collapsed and vice versa	`CustomEvent<{ collapse: boolean; }>`
`bqSelect`	Fires when the active or selected menu item changes	`CustomEvent<HTMLBqSideMenuItemElement>`

Event	Description	Type
`bqBlur`	Fires when the menu item loses focus	`CustomEvent<HTMLBqSideMenuItemElement>`
`bqClick`	Fires when the menu item is clicked	`CustomEvent<HTMLBqSideMenuItemElement>`
`bqFocus`	Fires when the menu item receives focus	`CustomEvent<HTMLBqSideMenuItemElement>`

In React, prefix events with on: onBqSelect, onBqCollapse, onBqClick.
In Angular, use event binding syntax: (bqSelect), (bqCollapse), (bqClick).
In Vue, use the @ shorthand: @bqSelect, @bqCollapse, @bqClick.

Methods

Method	Description	Returns
`toggleCollapse()`	Toggles the collapse state of the side menu	`Promise<void>`

CSS custom properties

Variable	Description	Default
`--bq-side-menu--bg-color`	Side menu background color	`var(--bq-background--primary)`
`--bq-side-menu--brand-color`	Side menu logo color	`var(--bq-background--brand)`
`--bq-side-menu--border-color`	Side menu border color	`var(--bq-stroke--primary)`
`--bq-side-menu--footer-box-shadow`	Side menu footer box shadow	`0 -10px 12px -12px var(--bq-background--tertiary)`

Variable	Description	Default
`--bq-side-menu-item--bg-default`	Side menu item default background color	`transparent`
`--bq-side-menu-item--bg-active`	Side menu item active background color	`var(--bq-ui--brand-alt)`
`--bq-side-menu-item--text-default`	Side menu item default text color	`var(--bq-text--primary)`
`--bq-side-menu-item--text-active`	Side menu item active text color	`var(--bq-text--brand)`
`--bq-side-menu-item--paddingX`	Side menu item horizontal padding	`var(--bq-spacing-l)`
`--bq-side-menu-item--paddingY`	Side menu item vertical padding	`var(--bq-spacing-m)`

Learn more about styling with shadow parts and CSS custom properties.

Resources

Interactive playground

Explore all side menu configurations in Storybook

Source code

View the component source on GitHub

​When to use

​Patterns

Default view

Collapsible view

​Anatomy

​Design guidelines

​Usage

​Default

​Side menu item behavior

​Side menu item states

​Options

​Appearance

​Default

​Brand

​Inverse

​Size

​With footer

​Collapse

​Best practices

​Accessibility

​API reference

​Properties

​bq-side-menu

​bq-side-menu-item

​Slots

​bq-side-menu

​bq-side-menu-item

​Shadow parts

​bq-side-menu

​bq-side-menu-item

​Events

​bq-side-menu

​bq-side-menu-item

​Methods

​CSS custom properties

​bq-side-menu

​bq-side-menu-item

​Resources

Interactive playground

Source code

When to use

Patterns

Anatomy

Design guidelines

Usage

Default

Side menu item behavior

Side menu item states

Options

Appearance

Default

Brand

Inverse

Size

With footer

Collapse

Best practices

Accessibility

API reference

Properties

`bq-side-menu`

`bq-side-menu-item`

Slots

`bq-side-menu`

`bq-side-menu-item`

Shadow parts

`bq-side-menu`

`bq-side-menu-item`

Events

`bq-side-menu`

`bq-side-menu-item`

Methods

CSS custom properties

`bq-side-menu`

`bq-side-menu-item`

Resources