@gfazioli/mantine-split-pane
A Mantine component that manages split panes allows users to divide and resize content areas within a layout efficiently
Update to v2
Note well
This version of the package is a complete rewrite of the previous version. We have rewritten the component to address some limitations of the previous version, particularly with multiple panes. We have made the
Split.Resizer
component visible and usable so that it can be customized and managed more easily. The API has changed, and some props have been removed or modified.↓ Follow the instructions below to update your code ↓
Breaking changes
- Added the new
Split.Resizer
component to manage the resizer between the panes. TheSplit.Resizer
component is now a child of theSplit
component and is used to manage the resizing of the panes. - The
Split
component structure has changed. TheSplit
component now needs theSplit.Pane
component as as well as theSplit.Resizer
component. - The
Split.Pane
component props have changed. We have moved the resizer props to theSplit.Resizer
component. TheSplit.Pane
component now only accepts props related to the pane itself. - The
Split.Pane
onDoubleClick
prop has been removed. You can now use theonResetInitialSize
event to manage the double click event. TheonResetInitialSize
event is triggered when the user double clicks on the resizer to reset the initial size of the pane. - You can still use the
onDoubleClick
prop to manage the double click event in theSplit.Resizer
component. - The
step
andshiftStep
props are now accessible both for theSplit
andSplit.Resizer
components. Those props are not accessible for theSplit.Pane
component.
JSX structure v1
JSX structure v2
- In the
Split.Pane
component all props related to the resizer have been removed. Now you can use theSplit.Resizer
component to manage the resizer between the panes. Have a look at the Props section for more information.
Installation
After installation import package styles at the root of your application:
You can import styles within a layer @layer mantine-split-pane
by importing @gfazioli/mantine-split-pane/styles.layer.css
file.
Usage
The main component for creating a Split pane is Split
, which accepts two or more children, Split.Pane
. Between each Split.Pane
you need to add a Split.Resizer
component. The Split.Resizer
component is used to manage the resizing of the panes.
Pane number 1
Pane number 2
Note well
In the example above, the
Paper
component's width and height are set to100%
to fill the available space. Below are examples without this setting.
Inline
By default, each Split
is displayed using flex
, but in case you want to display the panels inline, you can use the inline
prop.
Pane 1a
Pane 2a
Pane 1b
Pane 2b
Split.Resizer component
Starting from version 2, the Split.Resizer
component is a child component of Split
and allows setting some props for the resizer management. It is the component that will be used to resize the panes.
You don't need to set the Split.Resizer
properties for each resizer, as they inherit these properties from the Split
component.
In the example below, the first instance shows the Split.Resizer
component inheriting props from the Split
component. In contrast, the second instance shows the Split.Resizer
component with its own props.
Pane 1
Pane 2
Pane 3
Pane 1
Pane 2
Pane 2
onResizeStart, onResizing, and onResizeEnd events
The Split.Resizer
provides the same events onResizeStart
, onResizing
, and onResizeEnd
that are available in the Split.Pane
. However, pay attention to the difference in the parameter found in onResizing
and onResizeEnd
. In the case of the Split.Resizer
, the parameter is an object with the properties width
and height
for both panes; the one on the left (or top) beforePane
and the one on the right (or bottom) afterPane
.
The events released are therefore:
Pane 1
Pane 2
Start: false
End (beforePanePane 1): w= h=
End (afterPanePane 1): w= h=
Resizing (beforePanePane 1): w= h=
Resizing (afterPanePane 1): w= h=
Split.Pane component
The Split.Pane
component is a child component of Split
and allows setting some props for panel management. It is the container which will be resized by the Split.Resizer
component. It's very important because you can set the initial size of the pane, the minimum and maximum size of the pane, and the grow
property.
initialWidth=200 | initialWidth=300
Pane 1
Pane 2
initialWidth=400, minWidth=100 | initialWidth=200, minWidth=50
Pane 1
Pane 2
initialWidth="33%", maxWidth="40%"
Pane 1
Pane 2
Pane 3
initialWidth, initialHeight
The initial size as well as the min and max size of the pane can be set using the initialWidth
, initialHeight
, minWidth
, maxWidth
, minHeight
, and maxHeight
props. You may use a numeric value or a string with a unit (px, %) for the size of the pane. The initialWidth
and initialHeight
props are used to set the initial size of the pane, while the minWidth
, maxWidth
, minHeight
, and maxHeight
props are used to set the minimum and maximum size of the pane.
Pane 1
Pane 2
minWidth, maxWidth, minHeight, maxHeight
The minimum and maximum sizes of the panes can be set using the minWidth
, maxWidth
, minHeight
, and maxHeight
props. These props allow you to control the resizing behavior of the panes, ensuring they do not shrink or grow beyond specified limits.
Pane 1
initialWidth: 200
initialHeight: 200
minWidth: 180
maxWidth: 300
Width: px
Height: px
Pane 2
initialWidth: 40%
initialHeight: 400
minHeight: 300
maxHeight: 500
Width: px
Height: px
Note well
When resizing the panes, both will adjust simultaneously. This means the maximum and minimum values affect each other. For example, the minimum width of the second panel can impact the maximum width of the first panel. Choose the values carefully.
grow
The grow
property is only accessible for Split.Pane
and enables the panel size to expand and occupy the available space. It is especially handy for establishing a dynamic layout or, as illustrated below, for crafting a layout with two centered panels.
Below the grow
property is set to true
for the first pane and false
for the second pane. The first pane will occupy all the available space, while the second pane will occupy only the space needed for its content.
Pane 1
Pane 2
Below the grow
property is set to true
for the second pane and false
for the first pane. The second pane will occupy all the available space, while the first pane will occupy only the space needed for its content.
Pane 1
Pane 2
Below an interesting example of a layout with three panes. The first and third panes are set to grow={false}
and the second pane is set to grow={true}
. The second pane will occupy all the available space, while the first and third panes will occupy only the space needed for their content.
Pane 1
Pane 2
Pane 2
Of course, the grow feature can be use also when the orientation is vertical. In the example below, the first pane is set to grow={false}
and the second pane is set to grow={true}
. The second pane will occupy all the available space, while the first pane will occupy only the space needed for its content.
Pane 1
Pane 2
💡 Suggestions
Try to use the
grow
property with theinitialWidth
,initialHeight
,minWidth
,maxWidth
,minHeight
, andmaxHeight
props to create a dynamic layout.
onResizeStart, onResizing, and onResizeEnd events
The Split.Pane
provides the same events onResizeStart
, onResizing
, and onResizeEnd
that are available in the Split.Resizer
. However, pay attention to the difference in the parameter found in onResizing
and onResizeEnd
. In the case of the Split.Pane
, the parameter is an object with the properties width
and height
of the selected pane.
The events released are therefore:
Pane 1
Pane 2
Start: false
End (Pane 1): w= h=
Resizing (Pane 1): w= h=
Multiple Panes
You can add as many panes as you want, and you can also set the minWidth
and maxWidth
props for each pane along with other props.
Pane 1
Pane 2
Pane 3
initialWidth={280} maxWidth={300}
Pane 4
Reset with Double Click
You can reset the size of the panes by double-clicking on the separator.
Resize the panes, then double-click the resizer to reset their size.
Pane 1
Pane 2
Custom Double Click
You can also manage double click to swap two different dimensions in rotation. In the example below, double click changes the dimension by alternating the values of the initialWidth
property.
Double-click on the resizer to swap the initial width of the panes.
Pane 1
Pane 2
Note well
The
onResetInitialSize
event is triggered when the user double clicks on the resizer to reset the initial size of the pane. You can use this event to manage the double click event in theSplit.Pane
component. The code below shows how to use theonResetInitialSize
event to manage the double click event in theSplit.Pane
component.Alternatively, which is the same:
Nested Split
Naturally, you can nest Split
components to create more intricate layouts.
Pane 1
Pane 2
Pane 3
Nested Split with different props
Now you can appreciate the flexibility of the Split
component, which allows you to create complex layouts with different props for each Split
component.
Pane 1
Pane 2
Pane 3
Note well
Remember that you can set the resizer props both on the
Split
component and theSplit.Resizer
component. TheSplit.Resizer
component will inherit the props from theSplit
component, but you can override them by setting them on theSplit.Resizer
component.For example, in the code below, the
Split.Resizer
component will inherit thespacing
andradius
prop from theSplit
component.The same with:
Store the layout
You can store the layout of the panes and restore it later using the browser localStorage
or any other storage system.
Try to change the layout and refresh the page to see the layout restored.
Pane 1
Pane 2
As previously explained, you can choose to use events from either the Split.Pane
or the Split.Resizer
. Here, the code uses events from the Split.Pane
, but you can easily use events from the Split.Resizer
and decide to store a specific pane or both panels.
Accessibility
You may also use the Keyboard to navigate through the panes. Use the Tab
key to navigate through the resizer and the Arrow keys to resize the panes. You may use ◀︎ ▶︎ for horizontal panes and ▼ ▲ for vertical panes.
By default, the Arrow
keys will resize the panes by 8
pixel, but you can change this value using the step
prop.
Keeping the SHIFT key pressed while using the Arrow
keys will resize the panes by 64
pixel, but you can change this value using the shiftStep
prop.
Pane 1
Pane 2
Pane 1
Pane 2
Note well
The
step
andshiftStep
props are accessible both for theSplit
andSplit.Resizer
components. Obviously, thestep
andshiftStep
props of theSplit.Resizer
component will override thestep
andshiftStep
props of theSplit
component.In the above example, the resizer between the Pane 1 and Pane 2 will resize the panes by
32
pixel, and the resizer between the Pane 2 and Pane 3 will resize the panes by16
pixel. TheSHIFT
key will resize the panes by256
pixel between the Pane 1 and Pane 2 and by128
pixel between the Pane 2 and Pane 3.