Introducing PrimeReact v11-alpha 🎉Discover Now

useSidebar

Headless hooks for managing sidebar state, collapse behavior, layout coordination, and collapsible menu items.

Dashboard

Select an item from the sidebar to get started.

basic-demo

Usage#

import { useSidebar, useSidebarLayout, useSidebarMenuItem } from '@primereact/headless/sidebar';

useSidebar#

Manages a single sidebar's open/collapse state.

const { rootProps, state, toggle, expand, collapse } = useSidebar({
    defaultOpen: true,
    collapsible: 'icon'
});
 
return <aside {...rootProps}>...</aside>;

Props#

PropTypeDefaultDescription
idstring—Unique identifier for layout registration
layoutuseSidebarLayoutExposes—Layout context for multi-sidebar support
side'left' | 'right''left'Sidebar position
variant'sidebar' | 'floating' | 'inset''sidebar'Visual variant
collapsible'icon' | 'offcanvas' | 'none''icon'Collapse behavior
overlaybooleanfalseOverlay content instead of pushing
openboolean—Controlled open state
defaultOpenbooleantrueInitial open state
onOpenChangefunction—Called when open state changes
openOnHoverbooleanfalseOpen on pointer enter
hoverOpenDelaynumber50Delay before opening on hover (ms)
hoverCloseDelaynumber100Delay before closing on hover leave (ms)
widthstring'16rem'Expanded width
iconWidthstring'3rem'Icon-collapsed width

Data Attributes#

The rootProps include data attributes for CSS styling:

AttributeValues
data-stateexpanded | collapsed
data-variantsidebar | floating | inset
data-collapsibleoffcanvas | icon | (empty when expanded)
data-collapsible-modeoffcanvas | icon | none (always present)
data-sideleft | right
data-overlaypresent when overlay is true

useSidebarLayout#

Coordinates multiple sidebars, manages backdrop state, and provides toggle/collapse methods.

const layout = useSidebarLayout({});
 
// Pass layout to each sidebar
const sidebar = useSidebar({ id: 'nav', layout, collapsible: 'icon' });

Returns#

PropertyTypeDescription
register(id, entry) => voidRegister a sidebar
unregister(id) => voidUnregister a sidebar
toggle(target?) => voidToggle a sidebar by id, or the only sidebar
collapse(target?) => voidCollapse a sidebar by id, or all open sidebars
getEntry(id) => entryGet a sidebar entry by id
getEntries() => MapGet all sidebar entries
notifyChange() => voidNotify layout of state change
backdropPropsobjectProps for the backdrop element (onClick, data-state)
backdropMotionPropsobjectMotion props for backdrop (visible, motionProps)

useSidebarMenuItem#

Manages collapsible menu item state for expandable submenus.

const { state, triggerProps, contentProps } = useSidebarMenuItem({
    collapsible: true,
    defaultOpen: false
});
 
return (
    <li>
        <button {...triggerProps}>Menu Item</button>
        {state.open && <ul {...contentProps}>...</ul>}
    </li>
);

Props#

PropTypeDefaultDescription
collapsiblebooleanfalseEnable collapse/expand
openboolean—Controlled open state
defaultOpenbooleanfalseInitial open state
onOpenChangefunction—Called when open state changes