react-resizable-panels: React components for resizable panel groups/layouts.
Support
If you like this project there are several ways to support it:
- Become a GitHub sponsor
- or buy me a coffee
Installation
Begin by installing the library from NPM:
npm install react-resizable-panels
TypeScript types
TypeScript definitions are included within the published dist folder
FAQs
Frequently asked questions can be found here.
Documentation
Documentation for this project is available at react-resizable-panels.vercel.app.
Group
A Group wraps a set of resizable Panel components.
Group content can be resized horizontally or vertically.
Group elements always include the following attributes:
<div data-group data-testid="group-id-prop" id="group-id-prop">
ℹ️ Test id can be used to narrow selection when unit testing.
Required props
None
Optional props
| Name | Description |
|---|
| className | CSS class name.
|
| id | Uniquely identifies this group within an application.
Falls back to useId when not provided.
ℹ️ This value will also be assigned to the data-group attribute.
|
| style | CSS properties.
⚠️ The following styles cannot be overridden: display, flex-direction, flex-wrap, and overflow.
|
| children | Panel and Separator components that comprise this group.
|
| defaultLayout | Default layout for the Group.
ℹ️ This value allows layouts to be remembered between page reloads.
⚠️ Slight layout shift may occur when server-rendering panels with percentage-based default sizes.
Refer to the documentation for suggestions on how to minimize the impact of this.
|
| disableCursor | This library sets custom mouse cursor styles to indicate drag state.
Use this prop to disable that behavior for Panels and Separators in this group.
|
| disabled | Disable resize functionality.
|
| elementRef | Ref attached to the root HTMLDivElement.
|
| groupRef | Exposes the following imperative API:
getLayout(): LayoutsetLayout(layout: Layout): void
ℹ️ The useGroupRef and useGroupCallbackRef hooks are exported for convenience use in TypeScript projects.
|
| onLayoutChange | Called when the Group's layout is changing.
⚠️ For layout changes caused by pointer events, this method is called each time the pointer is moved.
For most cases, it is recommended to use the onLayoutChanged callback instead.
|
| onLayoutChanged | Called after the Group's layout has been changed.
ℹ️ For layout changes caused by pointer events, this method is not called until the pointer has been released.
This method is recommended when saving layouts to some storage api.
ℹ️ The second argument contains meta information about the layout change.
The isUserInteraction attribute signals whether the resize was caused by direct user input.
It is true for resizes caused by pointer or keyboard input
and false for other triggers (e.g. imperative API calls, initial mount, etc.)
|
| resizeTargetMinimumSize | Minimum size of the resizable hit target area (either Separator or Panel edge)
This threshold ensures are large enough to avoid mis-clicks.
- Coarse inputs (typically a finger on a touchscreen) have reduced accuracy;
to ensure accessibility and ease of use, hit targets should be larger to prevent mis-clicks.
- Fine inputs (typically a mouse) can be smaller
ℹ️ Apple interface guidelines suggest 20pt (27px) on desktops and 28pt (37px) for touch devices
In practice this seems to be much larger than many of their own applications use though.
|
| orientation | Specifies the resizable orientation ("horizontal" or "vertical"); defaults to "horizontal"
|
Panel
A Panel wraps resizable content and can be configured with min/max size constraints and collapsible behavior.
Panel size props can be in the following formats:
- Percentage of the parent Group (0..100)
- Pixels
- Relative font units (em, rem)
- Viewport relative units (vh, vw)
ℹ️ Numeric values are assumed to be pixels.
Strings without explicit units are assumed to be percentages (0%..100%).
Percentages may also be specified as strings ending with "%" (e.g. "33%")
Pixels may also be specified as strings ending with the unit "px".
Other units should be specified as strings ending with their CSS property units (e.g. 1rem, 50vh)
Panel elements always include the following attributes:
<div data-panel data-testid="panel-id-prop" id="panel-id-prop">
ℹ️ Test id can be used to narrow selection when unit testing.
⚠️ Panel elements must be direct DOM children of their parent Group elements.
Required props
None
Optional props
| Name | Description |
|---|
| className | CSS class name.
⚠️ Class is applied to nested HTMLDivElement to avoid styles that interfere with Flex layout.
|
| id | Uniquely identifies this panel within the parent group.
Falls back to useId when not provided.
ℹ️ This prop is used to associate persisted group layouts with the original panel.
ℹ️ This value will also be assigned to the data-panel attribute.
|
| style | CSS properties.
⚠️ Style is applied to nested HTMLDivElement to avoid styles that interfere with Flex layout.
|
| collapsedSize | Panel size when collapsed; defaults to 0%.
|
| collapsible | This panel can be collapsed.
ℹ️ A collapsible panel will collapse when it's size is less than of the specified minSize
|
| defaultSize | Default size of Panel within its parent group; default is auto-assigned based on the total number of Panels.
ℹ️ Interpretation rules:
- Numbers are interpreted as pixels (e.g.
defaultSize={200} is 200 pixels)
- Strings without explicit units are interpreted as percentage (e.g.
defaultSize="50" is 50 percent)
- Use explicit units (e.g. "px", "%", "em", "rem", "vh", or "vw") to change interpretation
⚠️ Percentage based sizes may cause slight layout shift when server-rendering.
For more information see the documentation.
|
| disabled | When disabled, a panel cannot be resized either directly or indirectly (by resizing another panel).
|
| elementRef | Ref attached to the root HTMLDivElement.
|
| groupResizeBehavior | How should this Panel behave if the parent Group is resized?
Defaults to preserve-relative-size.
preserve-relative-size: Retain the current relative size (as a percentage of the Group)preserve-pixel-size: Retain its current size (in pixels)
ℹ️ Panel min/max size constraints may impact this behavior.
⚠️ A Group must contain at least one Panel with preserve-relative-size resize behavior.
|
| maxSize | Maximum size of Panel within its parent group; defaults to "100%".
ℹ️ Interpretation rules:
- Numbers are interpreted as pixels (e.g.
maxSize={200} is 200 pixels)
- Strings without explicit units are interpreted as percentage (e.g.
maxSize="50" is 50 percent)
- Use explicit units (e.g. "px", "%", "em", "rem", "vh", or "vw") to change interpretation
|
| minSize | Minimum size of Panel within its parent group; defaults to 0%.
ℹ️ Interpretation rules:
- Numbers are interpreted as pixels (e.g.
minSize={200} is 200 pixels)
- Strings without explicit units are interpreted as percentage (e.g.
minSize="50" is 50 percent)
- Use explicit units (e.g. "px", "%", "em", "rem", "vh", or "vw") to change interpretation
|
| onResize | Called when panel sizes change.
@param panelSize Panel size (both as a percentage of the parent Group and in pixels)
@param id Panel id (if one was provided as a prop)
@param prevPanelSize Previous panel size (will be undefined on mount)
|
| panelRef | Exposes the following imperative API:
collapse(): voidexpand(): voidgetSize(): numberisCollapsed(): booleanresize(size: number): void
ℹ️ The usePanelRef and usePanelCallbackRef hooks are exported for convenience use in TypeScript projects.
|
Separator
Separators are not required but they are recommended as they improve keyboard accessibility.
⚠️ Separator elements must be direct DOM children of their parent Group elements.
Separator elements always include the following attributes:
<div data-separator data-testid="separator-id-prop" id="separator-id-prop" role="separator">
ℹ️ Test id can be used to narrow selection when unit testing.
ℹ️ In addition to the attributes shown above, separator also renders all required WAI-ARIA properties.
Required props
None
Optional props
| Name | Description |
|---|
| className | CSS class name.
ℹ️ Use the data-separator attribute for custom hover and active styles
⚠️ The following properties cannot be overridden: flex-grow, flex-shrink
|
| id | Uniquely identifies the separator within the parent group.
Falls back to useId when not provided.
ℹ️ This value will also be assigned to the data-separator attribute.
|
| style | CSS properties.
ℹ️ Use the data-separator attribute for custom hover and active styles
⚠️ The following properties cannot be overridden: flex-grow, flex-shrink
|
| disabled | When disabled, the separator cannot be used to resize its neighboring panels.
ℹ️ The panels may still be resized indirectly (while other panels are being resized).
To prevent a panel from being resized at all, it needs to also be disabled.
|
| disableDoubleClick | When true, double-clicking this Separator will not reset its Panel to its default size.
|
| elementRef | Ref attached to the root HTMLDivElement.
|
