react-resizable-panels 4.15.3 → 4.16.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
<img src="https://react-resizable-panels.vercel.app/og.png" alt="react-resizable-panels logo" width="400" height="210" />
|
|
2
2
|
|
|
3
|
-
`react-resizable-panels`: React components for resizable panel groups
|
|
3
|
+
`react-resizable-panels`: React components for resizable layouts: panel groups, grids, and workspaces of tabsets that users can rearrange by dragging tabs.
|
|
4
4
|
|
|
5
5
|
## Support
|
|
6
6
|
|
|
@@ -817,3 +817,303 @@ multiple gridlines can be rendered along the same boundary (e.g. before and afte
|
|
|
817
817
|
</table>
|
|
818
818
|
|
|
819
819
|
<!-- Gridline:optional-props:end -->
|
|
820
|
+
|
|
821
|
+
### Workspace
|
|
822
|
+
|
|
823
|
+
<!-- Workspace:description:begin -->
|
|
824
|
+
A Workspace arranges tabsets that users can rearrange by dragging tabs:
|
|
825
|
+
between tabsets, within a tabset's list of tabs, or onto the edge of a tabset to split it.
|
|
826
|
+
Tabsets can be resized and maximized.
|
|
827
|
+
|
|
828
|
+
The layout is described by a serializable model (see `WorkspaceModel`).
|
|
829
|
+
Workspaces are uncontrolled: provide an initial model with the `defaultModel` prop, save changes from the `onModelChanged` callback,
|
|
830
|
+
and make changes using the imperative API (see `WorkspaceImperativeHandle`).
|
|
831
|
+
|
|
832
|
+
ℹ️ Tab content is not remounted when a tab is moved.
|
|
833
|
+
Its elements are moved within the document, though, which resets some browser state (e.g. iframes are reloaded).
|
|
834
|
+
|
|
835
|
+
Workspace elements always include the following attributes:
|
|
836
|
+
|
|
837
|
+
```html
|
|
838
|
+
<div data-workspace data-testid="workspace-id-prop" id="workspace-id-prop">
|
|
839
|
+
```
|
|
840
|
+
|
|
841
|
+
ℹ️ [Test id](https://testing-library.com/docs/queries/bytestid/) can be used to narrow selection when unit testing.
|
|
842
|
+
<!-- Workspace:description:end -->
|
|
843
|
+
|
|
844
|
+
#### Required props
|
|
845
|
+
|
|
846
|
+
<!-- Workspace:required-props:begin -->
|
|
847
|
+
|
|
848
|
+
<table>
|
|
849
|
+
<thead>
|
|
850
|
+
<tr>
|
|
851
|
+
<th>Name</th>
|
|
852
|
+
<th>Description</th>
|
|
853
|
+
</tr>
|
|
854
|
+
</thead>
|
|
855
|
+
<tbody>
|
|
856
|
+
<tr>
|
|
857
|
+
<td>defaultModel</td>
|
|
858
|
+
<td><p>Initial layout of the workspace.</p>
|
|
859
|
+
<p>ℹ️ Splits and tabsets may omit their ids; they're assigned ids based on their position (see <code>WorkspaceModelInput</code>).</p>
|
|
860
|
+
<p>ℹ️ This value is only used when the Workspace mounts; use the imperative <code>setModel</code> method to replace it later.</p>
|
|
861
|
+
</td>
|
|
862
|
+
</tr>
|
|
863
|
+
<tr>
|
|
864
|
+
<td>renderTabContent</td>
|
|
865
|
+
<td><p>Content of a tab.</p>
|
|
866
|
+
<p>ℹ️ Content is only re-rendered when its tab changes or this function does;
|
|
867
|
+
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,
|
|
868
|
+
so it should be memoized (e.g. with <code>useCallback</code>) when tab content is expensive to render.</p>
|
|
869
|
+
</td>
|
|
870
|
+
</tr>
|
|
871
|
+
</tbody>
|
|
872
|
+
</table>
|
|
873
|
+
|
|
874
|
+
<!-- Workspace:required-props:end -->
|
|
875
|
+
|
|
876
|
+
#### Optional props
|
|
877
|
+
|
|
878
|
+
<!-- Workspace:optional-props:begin -->
|
|
879
|
+
|
|
880
|
+
<table>
|
|
881
|
+
<thead>
|
|
882
|
+
<tr>
|
|
883
|
+
<th>Name</th>
|
|
884
|
+
<th>Description</th>
|
|
885
|
+
</tr>
|
|
886
|
+
</thead>
|
|
887
|
+
<tbody>
|
|
888
|
+
<tr>
|
|
889
|
+
<td>className</td>
|
|
890
|
+
<td><p>CSS class name.</p>
|
|
891
|
+
</td>
|
|
892
|
+
</tr>
|
|
893
|
+
<tr>
|
|
894
|
+
<td>id</td>
|
|
895
|
+
<td><p>Uniquely identifies this workspace within an application.
|
|
896
|
+
Falls back to <code>useId</code> when not provided.</p>
|
|
897
|
+
<p>ℹ️ This value will also be assigned to the <code>id</code> and <code>data-testid</code> attributes; (an explicit <code>data-testid</code> prop will take precedence).</p>
|
|
898
|
+
</td>
|
|
899
|
+
</tr>
|
|
900
|
+
<tr>
|
|
901
|
+
<td>style</td>
|
|
902
|
+
<td><p>CSS properties.</p>
|
|
903
|
+
</td>
|
|
904
|
+
</tr>
|
|
905
|
+
<tr>
|
|
906
|
+
<td>classNames</td>
|
|
907
|
+
<td><p>CSS class names for the elements the workspace renders within its root element:</p>
|
|
908
|
+
<ul>
|
|
909
|
+
<li><code>tabset</code>: root element of a tabset (<code>data-tabset</code>)</li>
|
|
910
|
+
<li><code>header</code>: contains a tabset's tab list and toolbar (<code>data-tabset-header</code>)</li>
|
|
911
|
+
<li><code>tabList</code>: contains a tabset's tabs (<code>data-tab-list</code>)</li>
|
|
912
|
+
<li><code>tab</code>: passed to <code>renderTab</code> with the rest of a tab's props (<code>data-tab</code>)</li>
|
|
913
|
+
<li><code>toolbar</code>: contains the content returned by <code>renderTabsetToolbar</code> (<code>data-tabset-toolbar</code>)</li>
|
|
914
|
+
<li><code>tabPanels</code>: contains a tabset's tab content (<code>data-tab-panels</code>)</li>
|
|
915
|
+
<li><code>tabContent</code>: the element each tab's content is rendered into (<code>data-tab-content</code>)</li>
|
|
916
|
+
<li><code>dropIndicator</code>: shows where a dragged tab will be dropped within a tabset's panels (<code>data-drop-indicator</code>)</li>
|
|
917
|
+
<li><code>dragPreview</code>: follows the pointer while a tab is dragged (<code>data-drag-preview</code>)</li>
|
|
918
|
+
</ul>
|
|
919
|
+
<p>ℹ️ Elements expose their state as data attributes (e.g. <code>data-tab-selected</code>), which can be used for styling.
|
|
920
|
+
Elements within a tabset also have a <code>data-tab-placement</code> attribute (see <code>tabPlacement</code>).</p>
|
|
921
|
+
<p>ℹ️ Like the render props, this object is part of what tabsets re-render for;
|
|
922
|
+
in large workspaces, define it outside of the component (or memoize it) rather than inline.</p>
|
|
923
|
+
</td>
|
|
924
|
+
</tr>
|
|
925
|
+
<tr>
|
|
926
|
+
<td>disabled</td>
|
|
927
|
+
<td><p>Locks the arrangement: tabs cannot be resized, dragged, dropped, or closed by the user.
|
|
928
|
+
Selecting tabs and maximizing tabsets still work.</p>
|
|
929
|
+
<p>ℹ️ This prop overrides the <code>disableClose</code> and <code>disableDrag</code> flags of individual tabs.</p>
|
|
930
|
+
</td>
|
|
931
|
+
</tr>
|
|
932
|
+
<tr>
|
|
933
|
+
<td>disableDrop</td>
|
|
934
|
+
<td><p>Prevents tabs from being dropped onto some (or all) targets.</p>
|
|
935
|
+
<p>Functions are called when the target under the pointer changes;
|
|
936
|
+
returning <code>true</code> rejects the target.</p>
|
|
937
|
+
</td>
|
|
938
|
+
</tr>
|
|
939
|
+
<tr>
|
|
940
|
+
<td>elementRef</td>
|
|
941
|
+
<td><p>Ref attached to the root <code>HTMLDivElement</code>.</p>
|
|
942
|
+
</td>
|
|
943
|
+
</tr>
|
|
944
|
+
<tr>
|
|
945
|
+
<td>hiddenTabBehavior</td>
|
|
946
|
+
<td><p>What happens to the content of tabs that are not selected.
|
|
947
|
+
Can be a function to choose per tab (e.g. based on its data).</p>
|
|
948
|
+
<ul>
|
|
949
|
+
<li><code>"keep-mounted"</code>: content stays mounted (and its effects keep running)</li>
|
|
950
|
+
<li><code>"activity"</code>: content stays mounted but is rendered within a hidden React <code><Activity></code> boundary, so its effects are unmounted;
|
|
951
|
+
requires React 19.2 (falls back to <code>"keep-mounted"</code> otherwise)</li>
|
|
952
|
+
<li><code>"unmount"</code>: content is unmounted</li>
|
|
953
|
+
</ul>
|
|
954
|
+
<p>ℹ️ Moving a tab never remounts its content.</p>
|
|
955
|
+
<p>⚠️ Its React state is preserved, but its elements are moved within the document, which resets some browser state:
|
|
956
|
+
iframes are reloaded, playing media is paused, and focused elements are blurred.</p>
|
|
957
|
+
</td>
|
|
958
|
+
</tr>
|
|
959
|
+
<tr>
|
|
960
|
+
<td>onModelChanged</td>
|
|
961
|
+
<td><p>Called after the model has changed (e.g. a tab was moved, selected, or closed, or a tabset was resized).</p>
|
|
962
|
+
<p>ℹ️ For changes caused by pointer events, this method is not called until the pointer has been released.
|
|
963
|
+
This method is recommended when saving models to some storage api.</p>
|
|
964
|
+
</td>
|
|
965
|
+
</tr>
|
|
966
|
+
<tr>
|
|
967
|
+
<td>renderDragPreview</td>
|
|
968
|
+
<td><p>Content of the element that follows the pointer while a tab is being dragged.
|
|
969
|
+
Defaults to the tab's title (or id).</p>
|
|
970
|
+
</td>
|
|
971
|
+
</tr>
|
|
972
|
+
<tr>
|
|
973
|
+
<td>renderEmptyTabset</td>
|
|
974
|
+
<td><p>Content shown in the panels of a tabset that has no tabs (e.g. "Drag a tab here"):
|
|
975
|
+
the root tabset of an empty workspace, or a tabset with the <code>keepWhenEmpty</code> flag.</p>
|
|
976
|
+
</td>
|
|
977
|
+
</tr>
|
|
978
|
+
<tr>
|
|
979
|
+
<td>renderSeparator</td>
|
|
980
|
+
<td><p>Separator rendered between the children of a split.
|
|
981
|
+
Should return a <code>Separator</code> (or <code>null</code> for no separator); defaults to an unstyled <code>Separator</code>.</p>
|
|
982
|
+
</td>
|
|
983
|
+
</tr>
|
|
984
|
+
<tr>
|
|
985
|
+
<td>renderTab</td>
|
|
986
|
+
<td><p>Renders a tab (within its tabset's tab list).
|
|
987
|
+
Spread <code>props</code> onto the returned element:
|
|
988
|
+
they make it a tab (its role and ARIA attributes, keyboard and pointer handling, and data attributes),
|
|
989
|
+
and attach a <code>ref</code> that dragging and keyboard focus depend on.</p>
|
|
990
|
+
<pre><code class="language-tsx">renderTab={(tab, props) => (
|
|
991
|
+
<div {...props}>
|
|
992
|
+
{tab.title}
|
|
993
|
+
<TabCloseButton />
|
|
994
|
+
</div>
|
|
995
|
+
)}
|
|
996
|
+
</code></pre>
|
|
997
|
+
<p>Individual props can be overridden or wrapped, e.g. to confirm before the Delete key closes a tab
|
|
998
|
+
(call <code>props.onKeyDown</code> for other keys).</p>
|
|
999
|
+
<p>⚠️ Merge <code>className</code> and <code>style</code> rather than replacing them (e.g. <code>style={{ ...props.style, padding: 4 }}</code>):
|
|
1000
|
+
they include the <code>tab</code> entries of the <code>classNames</code> and <code>styles</code> props, and <code>style</code> includes the <code>touch-action</code> that touch dragging depends on.</p>
|
|
1001
|
+
<p>ℹ️ Pointer and keyboard events from interactive descendants (<code>button</code> elements, <code>role="button"</code>, or elements with a <code>data-tab-ignore</code> attribute) are ignored,
|
|
1002
|
+
so clicking a button within a tab doesn't select or drag it.</p>
|
|
1003
|
+
<p>ℹ️ When this prop is not provided, tabs show their title (or id) followed by a <code>TabCloseButton</code>.</p>
|
|
1004
|
+
</td>
|
|
1005
|
+
</tr>
|
|
1006
|
+
<tr>
|
|
1007
|
+
<td>renderTabsetToolbar</td>
|
|
1008
|
+
<td><p>Content shown after a tabset's tab list (e.g. buttons to add a tab or maximize the tabset).</p>
|
|
1009
|
+
<p>ℹ️ The <code>useParentTabset</code> and <code>useParentTabsetState</code> hooks can be used within this content.</p>
|
|
1010
|
+
</td>
|
|
1011
|
+
</tr>
|
|
1012
|
+
<tr>
|
|
1013
|
+
<td>resizePreviewMode</td>
|
|
1014
|
+
<td><p>Controls whether pointer dragging updates sizes immediately,
|
|
1015
|
+
or renders overlay separator previews until the pointer is released.</p>
|
|
1016
|
+
</td>
|
|
1017
|
+
</tr>
|
|
1018
|
+
<tr>
|
|
1019
|
+
<td>serverRenderTabContent</td>
|
|
1020
|
+
<td><p>Render the content of selected tabs on the server.
|
|
1021
|
+
Can be a function to choose per tab (e.g. based on its data).</p>
|
|
1022
|
+
<p>Tab content is rendered through portals (so that moving a tab doesn't remount it), which React can't render on the server.
|
|
1023
|
+
Content opted into server rendering is rendered inline instead, then moved into a portal once hydration has finished.</p>
|
|
1024
|
+
<p>⚠️ That move remounts the content once (e.g. resetting its state and re-running its effects),
|
|
1025
|
+
so this is best suited to content that is cheap to mount and benefits from being in the server-rendered HTML.</p>
|
|
1026
|
+
<p>ℹ️ This prop has no effect for workspaces that are not server rendered.</p>
|
|
1027
|
+
</td>
|
|
1028
|
+
</tr>
|
|
1029
|
+
<tr>
|
|
1030
|
+
<td>styles</td>
|
|
1031
|
+
<td><p>CSS properties for the elements the workspace renders within its root element (see <code>classNames</code>).</p>
|
|
1032
|
+
</td>
|
|
1033
|
+
</tr>
|
|
1034
|
+
<tr>
|
|
1035
|
+
<td>tabPlacement</td>
|
|
1036
|
+
<td><p>Where tabs are placed relative to tab content.</p>
|
|
1037
|
+
<p>Tabs placed on the left or right are stacked ("vertical"):
|
|
1038
|
+
this determines how a dropped tab's position is found and which arrow keys move focus between tabs.</p>
|
|
1039
|
+
<p>ℹ️ Elements within a tabset have a <code>data-tab-placement</code> attribute, which can be used for styling (e.g. rotating tabs on the left or right).</p>
|
|
1040
|
+
<p>ℹ️ Tabsets can override this with the <code>tabPlacement</code> field of their model node.</p>
|
|
1041
|
+
</td>
|
|
1042
|
+
</tr>
|
|
1043
|
+
<tr>
|
|
1044
|
+
<td>tabsetMinHeight</td>
|
|
1045
|
+
<td><p>Minimum height of each tabset's content area (not including its header).</p>
|
|
1046
|
+
<p>ℹ️ Tabsets can override this with the <code>minHeight</code> field of their model node.</p>
|
|
1047
|
+
<p>ℹ️ Interpretation rules:</p>
|
|
1048
|
+
<ul>
|
|
1049
|
+
<li>Strings must specify a unit: "px", "em", "rem", "vh", or "vw" (e.g. <code>tabsetMinHeight: "200px"</code>)</li>
|
|
1050
|
+
<li>Percentages (and strings without units) are not allowed</li>
|
|
1051
|
+
</ul>
|
|
1052
|
+
</td>
|
|
1053
|
+
</tr>
|
|
1054
|
+
<tr>
|
|
1055
|
+
<td>tabsetMinWidth</td>
|
|
1056
|
+
<td><p>Minimum width of each tabset's content area (not including its header).</p>
|
|
1057
|
+
<p>ℹ️ Tabsets can override this with the <code>minWidth</code> field of their model node.</p>
|
|
1058
|
+
<p>ℹ️ Interpretation rules:</p>
|
|
1059
|
+
<ul>
|
|
1060
|
+
<li>Strings must specify a unit: "px", "em", "rem", "vh", or "vw" (e.g. <code>tabsetMinWidth: "200px"</code>)</li>
|
|
1061
|
+
<li>Percentages (and strings without units) are not allowed</li>
|
|
1062
|
+
</ul>
|
|
1063
|
+
</td>
|
|
1064
|
+
</tr>
|
|
1065
|
+
<tr>
|
|
1066
|
+
<td>workspaceRef</td>
|
|
1067
|
+
<td><p>Exposes the imperative API (see <code>WorkspaceImperativeHandle</code>).</p>
|
|
1068
|
+
<p>ℹ️ The <code>useWorkspaceRef</code> and <code>useWorkspaceCallbackRef</code> hooks are exported for convenience use in TypeScript projects.</p>
|
|
1069
|
+
</td>
|
|
1070
|
+
</tr>
|
|
1071
|
+
</tbody>
|
|
1072
|
+
</table>
|
|
1073
|
+
|
|
1074
|
+
<!-- Workspace:optional-props:end -->
|
|
1075
|
+
|
|
1076
|
+
### TabCloseButton
|
|
1077
|
+
|
|
1078
|
+
<!-- TabCloseButton:description:begin -->
|
|
1079
|
+
Closes the tab it is rendered within; render it within the element returned by the Workspace's `renderTab` prop:
|
|
1080
|
+
|
|
1081
|
+
```tsx
|
|
1082
|
+
renderTab={(tab, props) => (
|
|
1083
|
+
<div {...props}>
|
|
1084
|
+
{tab.title}
|
|
1085
|
+
<TabCloseButton />
|
|
1086
|
+
</div>
|
|
1087
|
+
)}
|
|
1088
|
+
```
|
|
1089
|
+
|
|
1090
|
+
The button renders nothing if closing is disabled (by the tab's `disableClose` flag or the Workspace's `disabled` prop).
|
|
1091
|
+
Its default `aria-label` is "Close" followed by the tab's title (or id).
|
|
1092
|
+
|
|
1093
|
+
To keep the tab open (e.g. to confirm unsaved changes first), call `event.preventDefault()` in an `onClick` handler:
|
|
1094
|
+
|
|
1095
|
+
```tsx
|
|
1096
|
+
<TabCloseButton
|
|
1097
|
+
onClick={(event) => {
|
|
1098
|
+
if (hasUnsavedChanges && !confirm("Discard unsaved changes?")) {
|
|
1099
|
+
event.preventDefault();
|
|
1100
|
+
}
|
|
1101
|
+
}}
|
|
1102
|
+
/>
|
|
1103
|
+
```
|
|
1104
|
+
|
|
1105
|
+
ℹ️ This button is not focusable by default (`tabIndex={-1}`), since tabs shouldn't contain focusable content;
|
|
1106
|
+
keyboard users can close the focused tab with Delete or Backspace.
|
|
1107
|
+
<!-- TabCloseButton:description:end -->
|
|
1108
|
+
|
|
1109
|
+
#### Required props
|
|
1110
|
+
|
|
1111
|
+
<!-- TabCloseButton:required-props:begin -->
|
|
1112
|
+
None
|
|
1113
|
+
<!-- TabCloseButton:required-props:end -->
|
|
1114
|
+
|
|
1115
|
+
#### Optional props
|
|
1116
|
+
|
|
1117
|
+
<!-- TabCloseButton:optional-props:begin -->
|
|
1118
|
+
None
|
|
1119
|
+
<!-- TabCloseButton:optional-props:end -->
|