Migration Guide

This page covers upgrading between major versions of react-pro-sidebar. Each section lists every breaking change and how to update your code.

v1 → v2

TL;DR — If you already control the sidebar through Sidebar props (collapsed, toggled, …) and don’t use useProSidebar / ProSidebarProvider, the only change you need is bumping React to >=18.

Breaking changes

1. useProSidebar and ProSidebarProvider removed

The hook-based control API (deprecated since v1.1) is gone. v2 is fully controlled — you own the collapsed / toggled state and pass it to Sidebar as props.

Before (v1):

import { ProSidebarProvider, useProSidebar, Sidebar, Menu, MenuItem } from 'react-pro-sidebar';
 
// 1. wrap the app
function Root() {
  return (
    <ProSidebarProvider>
      <App />
    </ProSidebarProvider>
  );
}
 
// 2. control via the hook
function App() {
  const { collapseSidebar, toggleSidebar, collapsed, broken } = useProSidebar();
  return (
    <>
      <Sidebar>
        <Menu>
          <MenuItem>Documentation</MenuItem>
        </Menu>
      </Sidebar>
      <button onClick={() => collapseSidebar()}>Collapse</button>
      <button onClick={() => toggleSidebar()}>Toggle</button>
    </>
  );
}

After (v2):

import { useState } from 'react';
import { Sidebar, Menu, MenuItem } from 'react-pro-sidebar';
 
// no provider needed
function App() {
  const [collapsed, setCollapsed] = useState(false);
  const [toggled, setToggled] = useState(false);
  const [broken, setBroken] = useState(false);
 
  return (
    <>
      <Sidebar
        collapsed={collapsed}
        toggled={toggled}
        onBackdropClick={() => setToggled(false)}
        onBreakPoint={setBroken}
      >
        <Menu>
          <MenuItem>Documentation</MenuItem>
        </Menu>
      </Sidebar>
      <button onClick={() => setCollapsed((c) => !c)}>Collapse</button>
      <button onClick={() => setToggled((t) => !t)}>Toggle</button>
    </>
  );
}

Mapping from the old hook to the new model:

2. defaultCollapsed prop removed

Use the controlled collapsed prop instead.

- <Sidebar defaultCollapsed />
+ const [collapsed, setCollapsed] = useState(true);
+ <Sidebar collapsed={collapsed} />

3. breakPoint="always" removed

Use "all" (the two were aliases; "always" had been deprecated).

- <Sidebar breakPoint="always" />
+ <Sidebar breakPoint="all" />

4. React 16 / 17 no longer supported

The peer dependency is now react >=18 / react-dom >=18. React 19 is supported. Upgrade React before upgrading this package.

Non-breaking improvements

• Smaller bundle — runtime dependencies (@emotion, @popperjs, classnames) are now externalized instead of bundled, so they dedupe with your app’s copies.
• Proper ESM + CJS + types — the package now ships a correct exports map, a types field, and both dist/index.js (CJS) and dist/index.mjs (ESM).
• Modern toolchain — built with tsup, tested with Vitest, documented with Storybook 10.

Migration checklist

• Remove <ProSidebarProvider> from your tree.
• Replace useProSidebar() with local state passed to Sidebar props.
• Replace onBreakPoint for the old broken value.
• Replace defaultCollapsed with collapsed.
• Replace breakPoint="always" with breakPoint="all".
• Ensure React >=18 is installed.
• Run your type-checker — removed exports surface as clear errors.

v0 → v1

For older v0.x upgrades (e.g. ProSidebar → Sidebar rename, SCSS removed in favor of emotion, classname overhaul to ps- prefix), see the historical entries in the Changelog under 1.0.0-alpha.1 and 1.0.0-alpha.8.