README.md

react-resizable-panels: React components for resizable layouts: panel groups, grids, and workspaces of tabsets that users can rearrange by dragging tabs.

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.

Components

Cell

A Cell occupies one or more tracks (columns and rows) within a Grid. Cells are resized along with the tracks they occupy.

Cell elements always include the following attributes:

<div data-cell data-testid="cell-id-prop" id="cell-id-prop">

ℹ️ Test id can be used to narrow selection when unit testing.

⚠️ Cell elements must be direct DOM children of their parent Grid elements.

Required props

Name	Description
column	Index of the (first) column this cell occupies.
row	Index of the (first) row this cell occupies.

Optional props

Name	Description
className	CSS class name.
id	Uniquely identifies this cell within the parent grid. Falls back to useId when not provided. ℹ️ This value will also be assigned to the id and data-testid attributes (an explicit data-testid prop will take precedence).
style	CSS properties. ⚠️ Grid placement properties are managed by the Cell and cannot be overridden.
children	Cell contents.
columnSpan	Number of columns this cell spans; defaults to 1.
elementRef	Ref attached to the root HTMLDivElement.
rowSpan	Number of rows this cell spans; defaults to 1.

Grid

A Grid arranges resizable Cells in two dimensions. Columns can be resized horizontally and rows can be resized vertically; dragging the point where a column boundary and a row boundary intersect resizes both.

Size constraints (e.g. min/max size, collapsible) are specified per track (column or row), using the same format as Panel props.

Cells can span multiple columns and/or rows. Track boundaries cannot be resized alongside of a cell that spans across them.

Grid elements always include the following attributes:

<div data-grid data-testid="grid-id-prop" id="grid-id-prop">

ℹ️ Test id can be used to narrow selection when unit testing.

Required props

Name	Description
columns	Grid columns; either the number of columns or an array of size constraints (one per column).
rows	Grid rows; either the number of rows or an array of size constraints (one per row).

Optional props

Name	Description
className	CSS class name.
id	Uniquely identifies this grid within an application. Falls back to useId when not provided. ℹ️ This value will also be assigned to the id and data-testid attributes (an explicit data-testid prop will take precedence).
style	CSS properties. ⚠️ Grid template and display properties are managed by the Grid and cannot be overridden.
children	Cell and Gridline components that comprise this grid. ⚠️ Cell and Gridline elements must be direct DOM children of their parent Grid element.
defaultLayout	Default layout for either or both of the Grid's axes. ℹ️ This value allows layouts to be remembered between page reloads.
disableCursor	This library sets custom mouse cursor styles to indicate drag state. Use this prop to disable that behavior for this grid.
disabled	Disable resize functionality.
elementRef	Ref attached to the root HTMLDivElement.
gridRef	Exposes the following imperative API: getLayout(): GridLayout getTrackById(axis: "column" | "row", id: string | number): GridTrackImperativeHandle getTrackByIndex(axis: "column" | "row", index: number): GridTrackImperativeHandle setLayout(layout: Partial<GridLayout>): GridLayout ℹ️ The useGridRef and useGridCallbackRef hooks are exported for convenience in TypeScript projects.
onLayoutChange	Called when the Grid'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 Grid's layout has been changed. ℹ️ For layout changes caused by pointer events, this callback is not called until the pointer has been released. This callback is recommended for saving layouts to storage.
resizeTargetMinimumSize	Minimum size of the resizable hit target area (either a Gridline or a Cell edge). This threshold ensures targets are large enough to avoid mis-clicks. ℹ️ Refer to the Group prop of the same name for more information.

Gridline

Resizes the columns (or rows) of a Grid.

For example:

// Rendered between columns 0 and 1 and spans all rows
<Gridline type="column" column={1} />

// Rendered between rows 0 and 1 and spans all columns
<Gridline type="row" row={1} />

// Rendered between columns 0 and 1 alongside of row 2 only
<Gridline type="column" column={1} row={2} rowSpan={1} />

A gridline should not be rendered alongside of a Cell that spans across its boundary (this includes disabled gridlines; in development builds, an error will be logged to the console); render multiple gridlines along the same boundary instead (e.g. before and after the spanning Cell).

ℹ️ Once a boundary contains a gridline, it can only be resized using gridlines; the parts of the boundary that aren't alongside of a gridline can't be dragged.

Where column and row gridlines intersect, dragging resizes both axes.

Gridlines are not required but they are recommended as they improve keyboard accessibility.

Gridline elements always include the following attributes:

<div aria-orientation="vertical" data-separator role="separator">

ℹ️ Column gridlines are vertical (aria-orientation="vertical") and row gridlines are horizontal (aria-orientation="horizontal").

ℹ️ In addition to the attributes shown above, gridlines also render all required WAI-ARIA properties.

⚠️ Gridline elements must be direct DOM children of their parent Grid elements.

ℹ️ Gridlines rendered by another component (rather than directly within the Grid) aren't detected until they mount, so server-rendered layouts may shift slightly during hydration.

Required props

Name	Description
type	Column gridlines are vertical; they resize the columns on either side of them. Row gridlines are horizontal; they resize the rows on either side of them.

Optional props

Name	Description
children	Gridline contents (e.g. a drag handle icon).
className	CSS class name. ℹ️ Use the data-separator attribute for custom hover and active styles
disabled	When disabled, the gridline cannot be used to resize its neighboring tracks. ℹ️ The tracks may still be resized indirectly (e.g. by an intersecting gridline or another boundary). To prevent a track from being resized at all, it needs to also be disabled.
elementRef	Ref attached to the root HTMLDivElement.
style	CSS properties. ⚠️ Grid placement properties are managed by the gridline and cannot be overridden.
column	When type is "column", the gridline is rendered along the leading (left) edge of this column (between it and the previous column); must be greater than 0 and less than the number of columns. When type is "row", index of the first column the gridline is rendered alongside of; defaults to 0.
row	When type is "column", index of the first row the gridline is rendered alongside of; defaults to 0. When type is "row", the gridline is rendered along the leading (top) edge of this row (between it and the previous row); must be greater than 0 and less than the number of rows.
rowSpan	Number of rows a column gridline spans; defaults to all rows (starting from row). ℹ️ Gridlines can span a subset of rows in order to avoid cells that span across the boundary they sit on; multiple gridlines can be rendered along the same boundary (e.g. above and below a spanning cell).
columnSpan	Number of columns a row gridline spans; defaults to all columns (starting from column). ℹ️ Gridlines can span a subset of columns in order to avoid cells that span across the boundary they sit on; multiple gridlines can be rendered along the same boundary (e.g. before and after a spanning cell).

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 id and data-testid attributes (an explicit data-testid prop will take precedence).
style	CSS properties. ⚠️ The default inline styles cannot be overridden, except for 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(): Layout setLayout(layout: Layout): Layout ℹ️ The useGroupRef and useGroupCallbackRef hooks are exported for convenience 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 callback is not called until the pointer has been released. This callback is recommended for saving layouts to storage. ℹ️ 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.) The requestedLayout attribute is the layout before constraints were applied for the current Group size; prefer it when persisting layouts.
resizePreviewMode	Controls whether pointer dragging updates Panel sizes immediately, or renders overlay separator previews until the pointer is released. Defaults to "panel" (immediate resizing); "separator" defers resizing until release. Customize previews using the SeparatorOverlay component.
resizeTargetMinimumSize	Minimum size of the resizable hit target area (either Separator or Panel edge). This threshold ensures targets 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 id and data-testid attributes (an explicit data-testid prop will take precedence).
style	CSS properties. ⚠️ The default inline styles cannot be overridden, except for overflow.
collapsedSize	Panel size when collapsed; defaults to 0%.
collapsedThreshold	Distance a collapsible panel must be resized past its minSize to collapse, or past its collapsedSize to expand. Defaults to half the distance between collapsedSize and minSize. For example if a panel declares collapsedSize="5%", collapsedThreshold="5%", and minSize="25%", it will collapse when resized below 20% and expand when resized above 10%. ℹ️ 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
collapsible	This panel can be collapsed. ℹ️ A collapsible panel will collapse when its size is less than 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. panelSize Panel size (both as a percentage of the parent Group and in pixels) id Panel id (if one was provided as a prop) prevPanelSize Previous panel size (will be undefined on mount)
panelRef	Exposes the following imperative API: collapse(): void expand(): void getSize(): PanelSize isCollapsed(): boolean resize(size: number | string): void ℹ️ The usePanelRef and usePanelCallbackRef hooks are exported for convenience 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 id and data-testid attributes (an explicit data-testid prop will take precedence).
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.
preview	Overrides the Group default preview for this Separator when resizePreviewMode is "separator".

TabCloseButton

Closes the tab it is rendered within; render it within the element returned by the Workspace's renderTab prop:

renderTab={(tab, props) => (
  <div {...props}>
    {tab.title}
    <TabCloseButton>×</TabCloseButton>
  </div>
)}

The button renders nothing if closing is disabled (by the tab's disableClose flag or the Workspace's disabled prop). Its content defaults to "×" (e.g. it can be replaced with an icon), and its default aria-label is "Close" followed by the tab's title (or id).

Its children, className, style, and title can also be functions of its state (see TabCloseButtonState):

<TabCloseButton title={({ tabTitle }) => `Close ${tabTitle}`} />

To keep the tab open (e.g. to confirm unsaved changes first), call event.preventDefault() in an onClick handler:

<TabCloseButton
  onClick={(event) => {
    if (hasUnsavedChanges && !confirm("Discard unsaved changes?")) {
      event.preventDefault();
    }
  }}
/>

ℹ️ This button is not focusable by default (tabIndex={-1}), since tabs shouldn't contain focusable content; keyboard users can close the focused tab with Delete or Backspace.

Required props

None

Optional props

Name	Description
children	Content of the element, or a function that returns it (given the component's state).
className	Class name of the element, or a function that returns it (given the component's state).
style	Inline styles of the element, or a function that returns them (given the component's state).
title	Tooltip of the element, or a function that returns it (given the component's state).

TabsetCollapseButton

Collapses (or expands) the tabset it is rendered within; render it within the content returned by the Workspace's renderTabsetToolbar prop. Its children, className, style, and title can be functions of its state (see TabsetCollapseButtonState), e.g. to show a different icon while the tabset is collapsed:

renderTabsetToolbar={() => (
  <TabsetCollapseButton title={({ isCollapsed }) => (isCollapsed ? "Expand" : "Collapse")}>
    {({ isCollapsed }) => (isCollapsed ? "▸" : "▾")}
  </TabsetCollapseButton>
)}

The button renders nothing if the tabset can't be collapsed (see ParentTabsetState.isCollapsible), or while it's maximized. While the tabset is collapsed only because it doesn't fit (see ParentTabsetState.isCollapsedToFit), it can't be expanded, so the button has aria-disabled="true".

Its aria-expanded attribute reflects whether the tabset is expanded, and its aria-controls attribute refers to the selected tab's panel; its default aria-label ("Collapse tabset") doesn't change, since aria-expanded describes the state.

To keep the tabset as it is, call event.preventDefault() in an onClick handler.

ℹ️ Clicking a tab of a collapsed tabset also expands it.

Required props

None

Optional props

Name	Description
children	Content of the element, or a function that returns it (given the component's state).
className	Class name of the element, or a function that returns it (given the component's state).
style	Inline styles of the element, or a function that returns them (given the component's state).
title	Tooltip of the element, or a function that returns it (given the component's state).

TabsetDragHandle

Drags the tabset it is rendered within; render it within the content returned by the Workspace's renderTabsetToolbar prop:

renderTabsetToolbar={() => (
  <TabsetDragHandle>⠿</TabsetDragHandle>
)}

By default, a tabset is dragged by the empty space in its header; once its header contains a drag handle, only the handle drags it. Any element with a data-tabset-drag-handle attribute is a drag handle; this component also sets touch-action: none, so that it can be dragged by touch.

The handle has a data-disabled attribute when the tabset can't be dragged (see useParentTabsetState), e.g. to hide it. Its children, className, style, and title can also be functions of its state (see TabsetDragHandleState):

<TabsetDragHandle title={({ isDisabled }) => (isDisabled ? undefined : "Drag tabset")}>
  ⠿
</TabsetDragHandle>

Required props

None

Optional props

Name	Description
children	Content of the element, or a function that returns it (given the component's state).
className	Class name of the element, or a function that returns it (given the component's state).
style	Inline styles of the element, or a function that returns them (given the component's state).
title	Tooltip of the element, or a function that returns it (given the component's state).

TabsetMaximizeButton

Maximizes (or restores) the tabset it is rendered within; render it within the content returned by the Workspace's renderTabsetToolbar prop. Its children, className, style, and title can be functions of its state (see TabsetMaximizeButtonState), e.g. to show a different icon while the tabset is maximized:

renderTabsetToolbar={() => (
  <TabsetMaximizeButton title={({ isMaximized }) => (isMaximized ? "Restore" : "Maximize")}>
    {({ isMaximized }) => (isMaximized ? "Restore" : "Maximize")}
  </TabsetMaximizeButton>
)}

The button renders nothing for the only tabset in a workspace (see ParentTabsetState.isRoot) and for floating tabsets, which can't be maximized.

Its aria-pressed attribute reflects whether the tabset is maximized; its default aria-label ("Maximize tabset") doesn't change, since aria-pressed describes the state.

To keep the tabset as it is, call event.preventDefault() in an onClick handler.

Required props

None

Optional props

Name	Description
children	Content of the element, or a function that returns it (given the component's state).
className	Class name of the element, or a function that returns it (given the component's state).
style	Inline styles of the element, or a function that returns them (given the component's state).
title	Tooltip of the element, or a function that returns it (given the component's state).

Workspace

A Workspace arranges tabsets that users can rearrange by dragging tabs: between tabsets, within a tabset's list of tabs, or onto the edge of a tabset to split it. Tabsets can be resized and maximized.

The layout is described by a serializable model (see WorkspaceModel). Workspaces are uncontrolled: provide an initial model with the defaultModel prop, save changes from the onModelChanged callback, and make changes using the imperative API (see WorkspaceImperativeHandle).

ℹ️ Tab content is not remounted when a tab is moved. Its elements are moved within the document, though, which resets some browser state (e.g. iframes are reloaded).

Workspace elements always include the following attributes:

<div data-workspace data-testid="workspace-id-prop" id="workspace-id-prop">

ℹ️ Test id can be used to narrow selection when unit testing.

Required props

Name	Description
defaultModel	Initial layout of the workspace. ℹ️ Splits and tabsets may omit their ids; they're assigned ids based on their position (see WorkspaceModelInput). ℹ️ This value is only used when the Workspace mounts; use the imperative setModel method to replace it later.
renderTabContent	Content of a tab. ℹ️ Content is only re-rendered when its tab changes or this function does; a function created while rendering (e.g. an inline arrow function) re-renders the content of every tab whenever the Workspace's parent re-renders, so it should be memoized (e.g. with useCallback) when tab content is expensive to render.

Optional props

Name	Description
className	CSS class name.
id	Uniquely identifies this workspace within an application. Falls back to useId when not provided. ℹ️ This value will also be assigned to the id and data-testid attributes (an explicit data-testid prop will take precedence).
style	CSS properties.
acceptExternalDrop	Lets the workspace accept drags that use the browser's drag and drop from outside of any workspace (e.g. an element of the application with the draggable attribute, a file, or a link from another application), showing the drop indicator while the drag is over the workspace, and creating a tab where it's dropped. The new tab is reported to onModelChanged with the "add" reason. ℹ️ disableDrop can't be called until the tab is created (when the drag is dropped), so a target it rejects is shown as accepted while dragging; the drop is ignored then. Drag sources within the application can use the imperative startExternalDrag method instead, which doesn't have this limitation. ℹ️ Elements within the workspace's tab content that handle the same drags themselves (by canceling the dragover and drop events) take precedence. ℹ️ This object is read when drag events are handled, so it doesn't need to be memoized.
classNames	CSS class names for the elements the workspace renders within its root element: tabset: root element of a tabset (data-tabset) header: contains a tabset's tab list and toolbar (data-tabset-header) tabList: contains a tabset's tabs (data-tab-list) tab: passed to renderTab with the rest of a tab's props (data-tab) toolbar: contains the content returned by renderTabsetToolbar (data-tabset-toolbar) tabPanels: contains a tabset's tab content (data-tab-panels) tabContent: the element each tab's content is rendered into (data-tab-content) dropIndicator: shows where a dragged tab will be dropped within a tabset's panels, or at an edge of the workspace (data-drop-indicator) dragPreview: follows the pointer while a tab or tabset is dragged (data-drag-preview) ℹ️ Elements expose their state as data attributes (e.g. data-tab-selected, or data-tabset-dragging while a tabset is dragged), which can be used for styling. Elements within a collapsed tabset have a data-tabset-collapsed attribute. Elements within a tabset also have a data-tab-placement attribute (see tabPlacement). ℹ️ The drop indicator is the same element for the whole drag (rendered within the workspace's root element), so it can be animated between regions and tabsets (e.g. transition: inset 250ms). Its data-region attribute is the region of a tabset's panels it covers, or its data-edge attribute is the edge of the workspace it's at; while a tab isn't over either, it has neither and isn't shown (opacity: 0). ℹ️ Like the render props, this object is part of what tabsets re-render for; in large workspaces, define it outside of the component (or memoize it) rather than inline.
copyTab	Lets tabs be copied by dragging them: a tab dropped while the copy modifier key is held (Option on macOS, Ctrl elsewhere) adds the copy this function returns, leaving the dragged tab where it was. The change is reported to onModelChanged with the "copy" reason. Returning null (or undefined) moves the dragged tab instead. If that move isn't allowed either (the disableDrop prop rejects it, the ids conflict, or it isn't a valid place to move the tab), nothing happens. ℹ️ The copy needs an id that isn't used by any other node of the workspace (e.g. crypto.randomUUID()); copies with ids that are in use are rejected (and the tab is moved instead). ℹ️ The workspace the tab is dropped into makes the copy, so a tab dragged from another workspace (see the dragGroup prop) is copied by the workspace it's dropped into (and is only copied if that workspace has this prop). tab The tab being dragged target Where the copy will be dropped
copyTabset	Lets tabsets be copied by dragging them (by their headers), like the copyTab prop does for tabs: a tabset dropped while the copy modifier key is held adds the copy this function returns, leaving the dragged tabset where it was. The change is reported to onModelChanged with the "copy" reason. The copy includes its tabs, which need ids that aren't used by any other node of the workspace too; the copyTab argument copies a tab: copyTabset={(tabset, copyTab) => ({ ...tabset, id: crypto.randomUUID(), tabs: tabset.tabs.map(copyTab) })} Returning null (or undefined) moves the dragged tabset instead. If that move isn't allowed either (the disableDrop prop rejects it, the ids conflict, a keepWhenEmpty tabset is dropped into another workspace, or it isn't a valid place to move the tabset), nothing happens. ℹ️ The copy's selected tab is the copy of the dragged tabset's selected tab (matched by position), unless the copy selects one of its own tabs. ℹ️ A copy dropped into a tab list (or onto the center of another tabset) only adds its tabs; its id and data are only used where it's added as a tabset. tabset The tabset being dragged copyTab Copies a tab with the copyTab prop (and the same drop target); without that prop (or if it returns null), the copy is a shallow copy of the tab with a new id target Where the copy will be dropped
disabled	Locks the arrangement: tabs cannot be resized, dragged, dropped, or closed by the user. Selecting tabs and maximizing tabsets still work. ℹ️ This prop overrides the disableClose and disableDrag flags of individual tabs.
disableDragBetweenApps	Keeps drags between workspaces (see dragGroup) within this copy of the application: tabs dragged from this workspace can't be dropped into other copies of the application (e.g. the application loaded in another browser window or tab), and tabs dragged from other copies can't be dropped into this workspace. Workspaces in popout windows rendered by this copy of the application (with portals) are still part of the group. Defaults to false, so that workspaces with the same dragGroup in other copies of the application from the same origin can exchange tabs.
disableDrop	Prevents tabs (and tabsets) from being dropped onto some (or all) targets. Functions are called when the target under the pointer changes; returning true rejects the target. ℹ️ While a tabset is dragged, this function is called for each of its tabs (see DisableDropArgs), so restrictions on where tabs can be dropped apply to dragged tabsets too. ℹ️ Tabs can also be dropped at the edges of the workspace (beside all of the other tabsets), within a few pixels of the edges of its layout (except over tabset headers, where the tab lists are) or within its root element's padding. These targets have an edge rather than a tabsetId; disableDrop={({ target }) => "edge" in target} turns them off.
dragGroup	Lets tabs (and tabsets) be dragged between workspaces with the same dragGroup, including workspaces in popout windows (opened by the application and rendered into with a portal) and in other copies of the application from the same origin, e.g. the application loaded in another browser window or tab (see disableDragBetweenApps). Dropping one into another workspace moves it there, keeping its id and data; both workspaces report the change to onModelChanged with the "transfer" reason. Mouse drags use the browser's drag and drop when this prop is set, since pointer events can't follow the pointer into another window. Touch drags still use pointer events, so they can't leave the window. ℹ️ Tab ids must be unique within the group; a tab can't be dropped into a workspace that already has a tab with its id (and a tabset with the keepWhenEmpty flag can't be dragged to another workspace). A tab dragged to another workspace is rendered by that workspace, so its content is mounted again. ⚠️ A tab dragged to another copy of the application is sent there with the structured clone algorithm (like postMessage), so its data must be cloneable (e.g. no functions); tabs whose data can't be cloned (and tabsets containing them) can only be dragged within their copy of the application. Copies loaded at different times may be running different versions of the application, so the other copy may need to handle tab data it doesn't recognize.
elementRef	Ref attached to the root HTMLDivElement.
hiddenTabBehavior	What happens to the content of tabs that are not selected. Can be a function to choose per tab (e.g. based on its data). "keep-mounted": content stays mounted (and its effects keep running) "activity": content stays mounted but is rendered within a hidden React <Activity> boundary, so its effects are unmounted; requires React 19.2 (falls back to "keep-mounted" otherwise) "unmount": content is unmounted ℹ️ Moving a tab never remounts its content. ⚠️ Its React state is preserved, but its elements are moved within the document, which resets some browser state: iframes are reloaded, playing media is paused, and focused elements are blurred.
onModelChanged	Called after the model has changed (e.g. a tab was moved, selected, or closed, or a tabset was resized). ℹ️ For changes caused by pointer events, this callback is not called until the pointer has been released. This callback is recommended for saving models to storage.
onTearOff	Called when a tab (or a whole tabset) is dropped outside of the window, e.g. to open it in a popup window. Return true to accept it, which removes it from this workspace (reported to onModelChanged with the "tear-off" reason); otherwise nothing changes. Tabs and tabsets can only be torn off if they could be dragged, and tabsets with the keepWhenEmpty flag can't be torn off. Without this prop, dropping a tab outside of the window does nothing. ⚠️ The Workspace can't tell whether the application showed the tab, so check whether window.open returned null (because the popup was blocked) and return false then to keep the tab; returning true removes it even if nothing shows it. ℹ️ This is called while the release of the pointer is being handled (which browsers treat as user input), so a popup can be opened from it. With the dragGroup prop, a tab is torn off when it's dropped outside of every window in the group; the end of those drags isn't treated as user input, so browsers block popups opened then unless the drag started a few seconds earlier at most (and Safari blocks them always). ⚠️ Deprecated: browsers don't reliably report where a drag that leaves the window ends, and some block popups opened at the end of a drag. Open popout windows from a button instead (see usePopoutWindows). This will be removed in the next major version. ❌ This prop has been deprecated. Open popout windows from a button instead (see usePopoutWindows).
renderDragPreview	Content of the element that follows the pointer while a tab is being dragged. Defaults to the tab's title (or id). ℹ️ The element has a data-tear-off attribute while releasing the pointer would tear off the tab (see the deprecated onTearOff prop).
renderTabsetDragPreview	Content of the element that follows the pointer while a whole tabset is being dragged. Defaults to the title (or id) of its selected tab followed by the number of other tabs being dragged (e.g. "One (+2)"), or the selected tab's renderDragPreview when that prop is set, or the tabset's id if it has no tabs. ℹ️ The element has a data-drag-type attribute: "tabset" while a tabset is dragged, and "tab" while a tab is. It also has a data-tear-off attribute while releasing the pointer would tear off the tabset (see the deprecated onTearOff prop).
renderEmptyTabset	Content shown in the panels of a tabset that has no tabs (e.g. "Drag a tab here"): the root tabset of an empty workspace, or a tabset with the keepWhenEmpty flag.
renderSeparator	Separator rendered between the children of a split. Should return a Separator (or null for no separator); defaults to an unstyled Separator. ℹ️ Without separators, tabsets can still be resized by dragging their edges (like Panels in a Group without separators), but separators are recommended: they can be resized with the keyboard, and an edge's hit area can overlap the tabs beside it (pressing there resizes the tabset rather than dragging the tab).
renderTab	Renders a tab (within its tabset's tab list). Spread props onto the returned element: they make it a tab (its role and ARIA attributes, keyboard and pointer handling, and data attributes), and attach a ref that dragging and keyboard focus depend on. renderTab={(tab, props) => ( <div {...props}> {tab.title} <TabCloseButton /> </div> )} Individual props can be overridden or wrapped, e.g. to confirm before the Delete key closes a tab (call props.onKeyDown for other keys). ⚠️ Merge className and style rather than replacing them (e.g. style={{ ...props.style, padding: 4 }}): they include the tab entries of the classNames and styles props, and style includes the touch-action that touch dragging depends on. ℹ️ Pointer and keyboard events from interactive descendants (button elements, role="button", or elements with a data-tab-ignore attribute) are ignored, so clicking a button within a tab doesn't select or drag it. ℹ️ When this prop is not provided, tabs show their title (or id) followed by a TabCloseButton.
renderTabsetToolbar	Content shown after a tabset's tab list (e.g. buttons to add a tab or maximize the tabset). ℹ️ The useParentTabset and useParentTabsetState hooks can be used within this content.
resizePreviewMode	Controls whether pointer dragging updates sizes immediately, or renders overlay separator previews until the pointer is released.
serverRenderTabContent	Render the content of selected tabs on the server. Can be a function to choose per tab (e.g. based on its data). Tab content is rendered through portals (so that moving a tab doesn't remount it), which React can't render on the server. Content opted into server rendering is rendered inline instead, then moved into a portal once hydration has finished. ⚠️ That move remounts the content once (e.g. resetting its state and re-running its effects), so this is best suited to content that is cheap to mount and benefits from being in the server-rendered HTML. ℹ️ This prop has no effect for workspaces that are not server rendered.
styles	CSS properties for the elements the workspace renders within its root element (see classNames).
tabPlacement	Where tabs are placed relative to tab content. Tabs placed on the left or right are stacked ("vertical"): this determines how a dropped tab's position is found and which arrow keys move focus between tabs. ℹ️ Elements within a tabset have a data-tab-placement attribute, which can be used for styling (e.g. rotating tabs on the left or right). ℹ️ "left" and "right" are the start and end of the tabset (its header is rendered before or after its content), so in a right-to-left layout (e.g. within dir="rtl") tabs placed on the "left" are on the right; styles for them should use logical properties (e.g. border-inline-end rather than border-right). ℹ️ Tabsets can override this with the tabPlacement field of their model node.
tabRemovalSelectionBehavior	Which tab is selected when a tabset's selected tab is removed (closed, or dragged to another tabset): "adjacent": the tab after it (or before it, if it was the last tab) "recent": the tabset's most recently selected tab (like an IDE's editor groups), falling back to "adjacent" if none of its other tabs has been selected ℹ️ In "recent" mode, each tabset's recently selected tabs are saved in the model (see TabsetNode.recentTabIds), so they're restored with the rest of the layout.
tabsetMinHeight	Minimum height of each tabset's content area (not including its header). ℹ️ Tabsets can override this with the minHeight field of their model node. ℹ️ Interpretation rules: Strings must specify a unit: "px", "em", "rem", "vh", or "vw" (e.g. tabsetMinHeight: "200px") Percentages (and strings without units) are not allowed
tabsetMinWidth	Minimum width of each tabset's content area (not including its header). ℹ️ Tabsets can override this with the minWidth field of their model node. ℹ️ Interpretation rules: Strings must specify a unit: "px", "em", "rem", "vh", or "vw" (e.g. tabsetMinWidth: "200px") Percentages (and strings without units) are not allowed
workspaceRef	Exposes the imperative API (see WorkspaceImperativeHandle). ℹ️ The useWorkspaceRef and useWorkspaceCallbackRef hooks are exported for convenience in TypeScript projects.

Imperative APIs

GridImperativeHandle

Imperative Grid API.

ℹ️ The useGridRef and useGridCallbackRef hooks are exported for convenience in TypeScript projects.

Methods

Name	Description
getLayout	Get the Grid's current layout: maps of column and row ids to percentages (0..100)
getTrackById	Imperative API for the column or row with the specified id (see GridTrackImperativeHandle). ℹ️ Tracks without an explicit id use their index (e.g. "0") as their id. ⚠️ An error will be thrown if the Grid does not contain a matching track. axis "column" or "row" id Track id
getTrackByIndex	Imperative API for the column or row at the specified index (see GridTrackImperativeHandle). ℹ️ The index is resolved to a track id when this method is called; the returned API continues to refer to that id. Tracks without an explicit id use their index as their id, so specify ids if the API needs to refer to the same track after tracks are added or removed before it. ⚠️ An error will be thrown if the index is out of range. axis "column" or "row" index Track index (starting at 0)
setLayout	Set a new layout for one or both of the Grid's axes. layout Map of column and/or row ids to percentages (numbers between 0..100)

GridTrackImperativeHandle

Imperative API for an individual Grid track (column or row); returned by GridImperativeHandle.getTrackById and GridImperativeHandle.getTrackByIndex.

ℹ️ Sizes are relative to the space available to the track's axis (e.g. the width of the Grid, minus gaps and gridlines, for a column).

Methods

Name	Description
collapse	Collapse the track to its collapsedSize. ⚠️ This method will do nothing if the track is not collapsible or if it is already collapsed.
expand	Expand a collapsed track to its most recent size. ℹ️ If restoring that size would require collapsing another track, the track expands to the largest size that fits instead (as long as that is at least its minSize). ⚠️ This method will do nothing if the track is not currently collapsed.
getSize	Get the current size of the track in pixels as well as a percentage of its axis (0..100).
isCollapsed	The track is currently collapsed.
resize	Update the track's size. Size can be in the following formats: Percentage of the axis (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) size New track size

GroupImperativeHandle

Imperative Group API.

ℹ️ The useGroupRef and useGroupCallbackRef hooks are exported for convenience in TypeScript projects.

Methods

Name	Description
getLayout	Get the Group's current layout as a map of Panel id to percentage (0..100)
setLayout	Set a new layout for the Group layout Map of Panel id to percentage (a number between 0..100)

PanelImperativeHandle

Imperative Panel API

ℹ️ The usePanelRef and usePanelCallbackRef hooks are exported for convenience in TypeScript projects.

Methods

Name	Description
collapse	Collapse the Panel to its collapsedSize. ⚠️ This method will do nothing if the Panel is not collapsible or if it is already collapsed.
expand	Expand a collapsed Panel to its most recent size. ℹ️ If restoring that size would require collapsing another Panel, the Panel expands to the largest size that fits instead (as long as that is at least its minSize). ⚠️ This method will do nothing if the Panel is not currently collapsed.
getSize	Get the current size of the Panel in pixels as well as a percentage of the parent group (0..100).
isCollapsed	The Panel is currently collapsed.
resize	Update the Panel's size. Size 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) size New panel size

WorkspaceImperativeHandle

Imperative Workspace API. The easiest way to interact with this API is to use the useWorkspaceRef and useWorkspaceCallbackRef hooks.

ℹ️ These methods are not restricted by disabled, disableClose, disableDrag, or disableDrop.

Methods

Name	Description
addTab	Add a tab to a tabset. ℹ️ If a tab with the same id already exists, it is selected instead (and its data is not changed). tab Tab to add options .tabsetId Tabset to add the tab to; defaults to the active tabset options .index Position within the tabset; defaults to the end options .select Select the new tab; defaults to true
closeTab	Close a tab.
closeTabset	Close a tabset, along with any tabs it contains (e.g. to remove an empty tabset with the keepWhenEmpty flag). ℹ️ Like the rest of the imperative API, this isn't restricted by tabs' disableClose flags. If the root tabset is closed, the workspace is left with an empty root tabset.
collapseTabset	Collapse a tabset to just its header. ℹ️ This has no effect unless the tabset has the collapsible flag (or is floating; see FloatingTabsetNode); the only tabset in a workspace, and tabsets whose siblings are all collapsed, can't be collapsed.
expandTabset	Expand a collapsed tabset to its previous size. ℹ️ Tabsets are shown at least at their minimum sizes (if they fit), even if the model's sizes are smaller (see TabsetNode.size). ℹ️ This has no effect on a tabset that's only collapsed to fit, which is expanded once it fits (see TabsetNode.collapsible).
floatTab	Move a tab into a new floating tabset (see WorkspaceModel.floating), on top of any other floating tabsets. ℹ️ Parts of the position and size that aren't specified default to those of the tab's tabset, offset slightly down and to the right (and moved, if needed, to fit within the workspace). ℹ️ This has no effect on the only tab of a floating tabset (unless the tabset has the keepWhenEmpty flag).
floatTabset	Move a tabset out of the layout, to float above it (see WorkspaceModel.floating), on top of any other floating tabsets. ℹ️ Parts of the position and size that aren't specified default to those of the tabset, offset slightly down and to the right (and moved, if needed, to fit within the workspace). ℹ️ This has no effect on the root tabset (which fills the workspace) or a tabset that's already floating. A maximized tabset is restored first.
getActiveTabsetId	Id of the tabset the user most recently interacted with (by pointer or focus).
getModel	Get the current model.
getTabListFreeSpace	Space (in pixels) in a tabset's tab list that its tabs don't use, e.g. how much a toolbar beside the tabs could grow before they overflow (and how much space an overflow menu needs to free up, once it's negative). ℹ️ The space is measured along the tab list: its width, or its height if its tabs are placed on the left or right (or the tabset is collapsed to a vertical strip). If the tab list can't shrink any further (e.g. it's 0px wide, beside a toolbar that doesn't shrink), the amount the header's content overflows the header is subtracted too, so it's still how much space a toolbar needs to free up. ℹ️ The tab list's --tab-list-free-space custom property has the same value (e.g. "120px"). ℹ️ Within a tabset (e.g. its toolbar), the useTabListFreeSpace hook returns this value (and re-renders when it changes).
getTabListOverflow	Ids of a tabset's tabs that are out of view (scrolled out of its tab list, which overflows), in the order they're shown; e.g. to list them in an overflow menu. ℹ️ The same array is returned until the tabs out of view change. Tabs that aren't rendered at all (e.g. hidden with display: none) aren't included. ℹ️ Within a tabset (e.g. its toolbar), the useTabListOverflow hook returns this value (and re-renders when it changes).
maximizeTabset	Maximize a tabset, so that it covers the rest of the workspace. ℹ️ This has no effect on the only tabset in a workspace (the root), which already fills it, or on a floating tabset. A maximized tabset is restored if it becomes the only one (e.g. after the other tabsets are closed).
moveTab	Move a tab to a position within a tabset's tab list, to a region of a tabset's content area, or to an edge of the workspace (in a new tabset beside all of the other tabsets). ℹ️ The "left" and "right" regions (and edges) are sides of the screen (so they're mirrored in right-to-left layouts). ℹ️ Floating tabsets can't be split, so a tab moved to an edge region of one is added to it instead (like the "center" region).
moveTabset	Move a tabset beside another tabset (by dropping it onto a region at the edge of that tabset's content area), or beside all of the other tabsets (at an edge of the workspace), or move its tabs into another tabset (at an index within its tab list, or onto the "center" of its content area). The "left" and "right" regions (and edges) are sides of the screen (so they're mirrored in right-to-left layouts). ℹ️ When its tabs are moved, the emptied tabset is removed (unless it has the keepWhenEmpty flag). ℹ️ A floating tabset moved beside another tabset (or to an edge of the workspace) is docked: it's moved into the layout, and stops floating. Floating tabsets can't be split, so a tabset moved to an edge region of one has its tabs moved into it instead (like the "center" region).
restoreTabset	Restore the maximized tabset (if there is one).
selectTab	Select a tab within its tabset. ℹ️ Like a tab selected any other way, it's scrolled into view if its tab list overflows.
setModel	Replace the model.
startExternalDrag	Start dragging a tab that isn't in the workspace yet, from an element outside of it (e.g. an item in a palette of widgets); call it from the element's pointerdown handler. The tab is dragged like tabs within the workspace are (with the same drop targets, drop indicator, and disableDrop checks, with the "new" source), and is added where it's dropped (reported to onModelChanged with the "add" reason). The drag starts once the pointer has moved a few pixels, so a press that doesn't move (e.g. a click) does nothing; the click that follows a drag is suppressed. Pressing Escape cancels the drag. ℹ️ Unlike other imperative methods, the drop is restricted by disabled and disableDrop, since the user chooses where it goes. ℹ️ The element must be in the same document as the workspace. Like tabs, it should have touch-action: none (e.g. with CSS), so that touch input drags it rather than scrolling the page. event The pointerdown event of the pressed element
subscribeToTabListFreeSpace	Subscribe to changes to the free space in a tabset's tab list (see getTabListFreeSpace), e.g. from a toolbar rendered outside of the Workspace. ℹ️ The listener is called synchronously when the tab list is measured (when it or its tabs change size, or tabs are added or removed), before the browser paints; changes it makes to the DOM (e.g. with flushSync) are shown in the same frame. ℹ️ The listener is called with undefined when the tabset is removed (e.g. closed, or merged into another tabset).
subscribeToTabListOverflow	Subscribe to changes to which of a tabset's tabs are out of view (see getTabListOverflow), e.g. from an overflow menu rendered outside of the Workspace. ℹ️ The listener is called synchronously when the tab list is measured (when it's scrolled, when it or its tabs change size, or when tabs are added or removed), before the browser paints, except while the user scrolls the list (it's reported in the scroll event, and the browser may show the new position first). ℹ️ The listener is called with undefined when the tabset is removed (e.g. closed, or merged into another tabset).
updateTab	Update a tab; fields that are not specified are not changed. ℹ️ data is replaced rather than merged.
updateTabset	Update a tabset; fields that are not specified are not changed. ℹ️ data is replaced rather than merged. ℹ️ Setting minHeight, minWidth, or tabPlacement to undefined removes the tabset's override, so the corresponding Workspace prop is used; setting maxHeight or maxWidth to undefined removes the maximum. ℹ️ The position and size (x, y, width, and height) of a floating tabset can be changed too (and are ignored for other tabsets), as can be its collapsible flag (which is ignored for floating tabsets).