Pluma
About
MCP Server
Getting started
Contributing
Breaking Changes
Changelog
Content
Icons
Motion
Style Utilities
Test Helpers
Tokens
Overview
Status
Accordion
AccordionGroup
Box
Card
CenterBaseline
Divider
EmptyState
Flex
FormLayout
Grid
InlineStack
Panel
Scrollable
Stack
Code
DescriptionList
Emphasis
Heading
List
Paragraph
Strong
Text
TextLabel
Truncated
Avatar
CodeBlock
Coin
Icon
Image
LabelIcon
Breadcrumbs
Link
NavItem
Page
Pagination
PlainLink
SideNav
Tabs
TabNav
Button
ButtonGroup
CloseButton
DropdownMenu
PlainButton
ToggleButton
Checkbox
CheckboxGroup
ColorPicker
Combobox
DatePicker
Form
JsonField
NumberField
OptionCard
OptionCardGroup
Radio
RadioGroup
Search
SegmentedControl
Select
Slider
TextArea
TextField
Toggle
Badge
DataTable
Filters
FormattedDateTime
FormattedRelativeTime
KeyboardShortcut
Label
ProgressBar
ProgressCircle
StatusIndicator
Table
Tag
Banner
PageLoader
SkeletonShape
SkeletonText
Snackbar
Spinner
Blanket
ConfirmationModal
Drawer
Modal
Modal manager
Popover
Tooltip
VisuallyHidden
Anti-patterns
Combobox with Add New
Density
Inline Form Controls
Refinement levers
Search with DropdownMenu
States
Voice
Ember Floating UI
Ember prop spreading
ModalPrimitive
PlumaProvider
PopoverPrimitive
Portal
React Yield
fly-alert
fly-badge
fly-btn
fly-card
fly-close
fly-label
fly-panel
fly-progress
fly-range
fly-spinner
fly-tag
Forms
Lists
Tailwind
Componentsv2.170.1
Iconsv1.15.0
MCPv0.8.18
Tokensv0.34.1

SideNav

Figma
Github
Storybook

A component to display a navigation sidebar.

Importing

The component can be imported via:

import { SideNav, SideNavGroup } from '@customerio/pluma-components/react';

Usage

SideNav is a vertical navigation component that contains NavItem, optionally wrapped in groups. The SideNav can be collapsed and expanded.

<Box display="flex" style={{ height: 400 }}>
  <SideNav>
    <SideNavGroup title="Manage">
      <NavItem href="#" icon="person" isSelected={true}>People</NavItem>
      <NavItem href="#" icon="object">Objects</NavItem>
    </SideNavGroup>
    <SideNavGroup title="Create">
      <NavItemExpandable defaultIsOpen={true}>
        <NavItemExpandableTrigger icon="layout">Content</NavItemExpandableTrigger>
        <NavItemExpandableContent>
          <NavItem href="#">Message Library</NavItem>
          <NavItem href="#">Assets</NavItem>
        </NavItemExpandableContent>
      </NavItemExpandable>
    </SideNavGroup>
  </SideNav>
</Box>

Default Collapsed State

Use defaultIsCollapsed to render the side navigation in a collapsed state initially. The user can still expand and collapse it using the toggle button.

<Box display="flex" style={{ height: 400 }}>
  <SideNav defaultIsCollapsed={true}>
    <SideNavGroup title="Manage">
      <NavItem href="#" icon="person" isSelected={true}>People</NavItem>
      <NavItemExpandable>
        <NavItemExpandableTrigger icon="database">Data & Integrations</NavItemExpandableTrigger>
        <NavItemExpandableContent>
          <NavItem href="#">Data Index</NavItem>
          <NavItem href="#">Integrations</NavItem>
          <NavItem href="#">Imports</NavItem>
        </NavItemExpandableContent>
      </NavItemExpandable>
    </SideNavGroup>
    <SideNavGroup title="Create">
      <NavItemExpandable defaultIsOpen={true}>
        <NavItemExpandableTrigger icon="layout">Content</NavItemExpandableTrigger>
        <NavItemExpandableContent>
          <NavItem href="#">Message Library</NavItem>
          <NavItem href="#">Assets</NavItem>
        </NavItemExpandableContent>
      </NavItemExpandable>
    </SideNavGroup>
  </SideNav>
</Box>

Controlled Collapse State

For full control over the collapse state, use isCollapsed together with onCollapseChange.

import { useState } from 'react';
import { Box,
  SideNav,
  SideNavGroup,
  NavItem,
  NavItemExpandable,
  NavItemExpandableTrigger,
  NavItemExpandableContent,
} from '@customerio/pluma-components/react';

export default function Example() {
  const [isCollapsed, setIsCollapsed] = useState(false);

  return (
    <Box display="flex" style={{ height: 400 }}>
      <SideNav isCollapsed={isCollapsed} onCollapseChange={setIsCollapsed}>
        <SideNavGroup title="Manage">
          <NavItem href="#" icon="person" isSelected={true}>People</NavItem>
          <NavItemExpandable>
            <NavItemExpandableTrigger icon="database">Data & Integrations</NavItemExpandableTrigger>
            <NavItemExpandableContent>
              <NavItem href="#">Data Index</NavItem>
              <NavItem href="#">Integrations</NavItem>
              <NavItem href="#">Imports</NavItem>
            </NavItemExpandableContent>
          </NavItemExpandable>
        </SideNavGroup>
        <SideNavGroup title="Create">
          <NavItemExpandable defaultIsOpen={true}>
            <NavItemExpandableTrigger icon="layout">Content</NavItemExpandableTrigger>
            <NavItemExpandableContent>
              <NavItem href="#">Message Library</NavItem>
              <NavItem href="#">Assets</NavItem>
            </NavItemExpandableContent>
          </NavItemExpandable>
        </SideNavGroup>
      </SideNav>
    </Box>
  );
}

Not Collapsible

Set isCollapsible to false to hide the collapse/expand toggle button.

<Box display="flex" style={{ height: 400 }}>
  <SideNav isCollapsible={false}>
    <SideNavGroup title="Manage">
      <NavItem href="#" icon="person" isSelected={true}>People</NavItem>
      <NavItem href="#" icon="object">Objects</NavItem>
    </SideNavGroup>
    <SideNavGroup title="Create">
      <NavItemExpandable defaultIsOpen={true}>
        <NavItemExpandableTrigger icon="layout">Content</NavItemExpandableTrigger>
        <NavItemExpandableContent>
          <NavItem href="#">Message Library</NavItem>
          <NavItem href="#">Assets</NavItem>
        </NavItemExpandableContent>
      </NavItemExpandable>
    </SideNavGroup>
  </SideNav>
</Box>

Groups

Use SideNavGroup to organize nav items into labeled sections. The title prop is optional — groups without a title still provide visual spacing between sections.

<Box display="flex" style={{ height: 650 }}>
  <SideNav>
    <SideNavGroup title="Manage">
      <NavItem href="#" icon="person" isSelected={true}>People</NavItem>
      <NavItemExpandable>
        <NavItemExpandableTrigger icon="database">Data & Integrations</NavItemExpandableTrigger>
        <NavItemExpandableContent>
          <NavItem href="#">Data Index</NavItem>
          <NavItem href="#">Integrations</NavItem>
          <NavItem href="#">Imports</NavItem>
          <NavItem href="#">Exports</NavItem>
          <NavItem href="#">Collections</NavItem>
        </NavItemExpandableContent>
      </NavItemExpandable>
    </SideNavGroup>
    <SideNavGroup title="Create">
      <NavItemExpandable defaultIsOpen={true}>
        <NavItemExpandableTrigger icon="layout">Content</NavItemExpandableTrigger>
        <NavItemExpandableContent>
          <NavItem href="#">Message Library</NavItem>
          <NavItem href="#">Assets</NavItem>
          <NavItem href="#">Email Layouts</NavItem>
          <NavItem href="#">Snippets</NavItem>
        </NavItemExpandableContent>
      </NavItemExpandable>
    </SideNavGroup>
    <SideNavGroup>
      <NavItem href="#" icon="manage">Settings</NavItem>
    </SideNavGroup>
  </SideNav>
</Box>

Provider

SideNavProvider manages the side navigation's collapse state at the top of your layout, making it accessible to any nested component via context. This is useful when components outside the SideNav itself need to read or control the collapse state.

When a SideNav is rendered inside a SideNavProvider, it automatically inherits the provider's state instead of managing its own.

The provider accepts the same state props as SideNav: isCollapsed, onCollapseChange, defaultIsCollapsed, and isCollapsible.

import {
  SideNavProvider,
  useSideNavState,
  useSetSideNavState,
  useToggleSideNav,
} from '@customerio/pluma-components/react';

Usage

In this example, the SideNavProvider wraps the entire layout. A button in the main content area uses useToggleSideNav to control the side navigation without needing direct access to the SideNav component.

Side nav is: expanded

import {
  Box,
  Stack, InlineStack,
  Button,
  NavItem,
  NavItemExpandable,
  NavItemExpandableContent,
  NavItemExpandableTrigger,
  Paragraph,
  SideNav,
  SideNavGroup,
  SideNavProvider,
  useSideNavState,
  useToggleSideNav,
} from '@customerio/pluma-components/react';

function ToggleContent() {
  const toggleSideNav = useToggleSideNav();

  return (
    <Box>
      <Button onClick={toggleSideNav}>
        Toggle side nav
      </Button>
    </Box>
  );
}

function StateContent() {
  const state = useSideNavState();
  return (
    <Box>
      <Paragraph>
        Side nav is: {state.isCollapsed ? 'collapsed' : 'expanded'}
      </Paragraph>
    </Box>
  );
}

export default function Example() {
  return (
    <SideNavProvider>
      <InlineStack alignBlock="stretch" style={{ height: 400 }}>
        <SideNav>
          <SideNavGroup title="Manage">
            <NavItem href="#" icon="person" isSelected={true}>People</NavItem>
            <NavItem href="#" icon="object">Objects</NavItem>
          </SideNavGroup>
          <SideNavGroup title="Create">
            <NavItemExpandable defaultIsOpen={true}>
              <NavItemExpandableTrigger icon="layout">Content</NavItemExpandableTrigger>
              <NavItemExpandableContent>
                <NavItem href="#">Message Library</NavItem>
                <NavItem href="#">Assets</NavItem>
              </NavItemExpandableContent>
            </NavItemExpandable>
          </SideNavGroup>
        </SideNav>

        <Stack p="200" gap="200">
          <ToggleContent />
          <StateContent />
        </Stack>
      </InlineStack>
    </SideNavProvider>
  );
}

API

PlumaSideNav extends Box

defaultIsCollapsed  boolean | undefined

Whether the side navigation is collapsed by default - use for uncontrolled collapse state when you want the side navigation to be in a specific state initially.

isCollapsed  boolean | undefined

Whether the side navigation is collapsed. Use for controlled collapse state.

isCollapsible  boolean | undefined

Default:true

Whether the side navigation can be collapsed and expanded. When false, the collapse/expand toggle button is hidden.

onCollapseChange  ((isCollapsed: boolean) => void) | undefined

A callback function that is called when the collapse state changes. Use in combination with isCollapsed for controlled collapse state.

PlumaSideNavProvider

defaultIsCollapsed  boolean | undefined

Whether the side navigation is collapsed by default - use for uncontrolled collapse state when you want the side navigation to be in a specific state initially.

isCollapsed  boolean | undefined

Whether the side navigation is collapsed. Use for controlled collapse state.

isCollapsible  boolean | undefined

Default:true

Whether the side navigation can be collapsed and expanded. When false, the collapse/expand toggle button is hidden.

onCollapseChange  ((isCollapsed: boolean) => void) | undefined

A callback function that is called when the collapse state changes. Use in combination with isCollapsed for controlled collapse state.

PlumaSideNavGroup extends Box

title  string | undefined

An optional title for the group, which can be used to provide context or categorization for the items within.

On this page

Importing
Usage
Default Collapsed State
Controlled Collapse State
Not Collapsible
Groups
Usage
API