You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This is intended to be **the** simple, reliable, configurable, and elegant solution to having splittable, draggable and collapsible panes in your React application.
The only component you must interact with is `SplitPane`. This serves as a wrapper for all of the children you wish to lay out.
63
64
64
-
The only component you must interact with is `SplitPane`. This serves as a wrapper for the children you wish to layout in a panel form.
65
+
All you're required to give is a `split` prop which can be either `"horizontal"` or `"vertical"`. This identifies what the orientation of the split panel will be.
65
66
66
-
Here's a basic example:
67
67
```tsx
68
68
<SplitPanesplit="vertical">
69
69
<div>This is the first div</div>
@@ -73,147 +73,40 @@ Here's a basic example:
73
73
</SplitPane>
74
74
```
75
75
76
-
This will split the children. The children can be any valid React child. If a child is `null` it will be excluded from being split or displayed.
76
+
What you just did is make a splittable panel layout!
77
77
78
-
**Note!**:eyes: There is no limit to the number of divs you have as children. The `SplitPane` will split them all accordingly.
78
+
## Congrats! That was easy! :grin:
79
79
80
-
## Styling the Resizer 💅
80
+
This basically splits the children vertically (i.e. full-height split). The children can be any valid React child. If a child is `null` it will be excluded from being split or displayed.
81
81
82
-
By default there is a 1px divider that starts out `rgba(120, 120, 120, 0.3)` and transitions to `rgba(120, 120, 120, 0.6)` on hover. Having a grey color with an alpha value means that it will look nice on both light and dark backgrounds.
82
+
By default there is a 1px divider with a grabbable surface of 1rem width or height (depending on the split).
83
83
84
-
This is easily replaceable with the `css` and `hoverCss` options. No need to worry about pseudo selectors, transitions, animations or anything. You just have to indicate what the divider should look like **before** and **after**. This is accomplished by having two separate divs, one of which fades out and the other which fades in.
85
84
86
-
**Note** 🚨 The css props must be valid `React.CSSProperties` objects.
85
+
There is also no limit to the number of divs you have as children. The `SplitPane` will split them all accordingly.
87
86
88
-
The sizer also has a grabbable surface that spans the height (or length) of the split and has a default grabbable surface of `1rem`. This is changeable by the `grabberSize` option which can be set to any valid CSS size value for `width`or `height`.
87
+
## But what about collapsing the panels, styling the resizer, or RTL support? :sob:
89
88
90
-
**Note!**:eyes: As per default React CSS, a number will be interpreted as a `px` value.
89
+
This library supports all of these things and more!
91
90
91
+
For more details check out [the documentation](https://collapse-pane.zurg.dev/)
92
92
93
-
Here's an example:
93
+
# Documentation
94
94
95
-
```tsx
96
-
<SplitPane
97
-
split="vertical"
98
-
resizerOptions={{
99
-
css: {
100
-
width: '1px',
101
-
background: 'rgba(0, 0, 0, 0.1)',
102
-
},
103
-
hoverCss: {
104
-
width: '3px',
105
-
background: '1px solid rgba(102, 194, 255, 0.5)',
106
-
},
107
-
grabberSize: '1rem',
108
-
}}
109
-
>
110
-
<div>This is the first div</div>
111
-
<div>This is the second div</div>
112
-
</SplitPane>
113
-
```
114
-
115
-
116
-
## Using a Collapse Button 🤹♀️
117
-
118
-
This is the killer feature of this library :eyes:
119
-
120
-
It's a common UX need to want to collapse the left or initial panel to give more room for another part of a site or app. This is easily accomplished by including several `CollapseOptions` as a prop to the `SplitPane`.
121
-
122
-
*`beforeToggleButton` - the element displayed as the collapse button **before** the panel is collapsed. This is an purely aesthetic component.
123
-
*`afterToggleButton` - the element displayed as the collapse button **after** the panel is collapsed. This is an purely aesthetic component.
124
-
*`buttonTransition` - the animation applied to the button appear/disappear. Possible options are `zoom`, `grow`, or `fade`
125
-
*`buttonTransitionTimeout` - the time (in millisecons) that the animation for the appear/disappear of the button will take place
126
-
*`buttonPositionOffset` - a positive or negative number that will either add or subtract the flex-basis (starting at 100) of an invisible div before or after the button. e.g. 50 would make the "before" 150 and the "after" 50
127
-
*`collapseDirection` - `'left' | 'right' | 'up' | 'down'` - this is used to indicate the direction that it should collapse. By default collapsing happens left and up for the vertical and horizontal splits respectively. Valid values for a vertical split are `left` or `right` and valid values for a horizontal split are `up` or `down`
128
-
*`collapseSize` - the size of the collapsed panel after it has been collapsed
129
-
*`collapseTransitionTimeout` - the duration within the collapse animation will take place
130
-
*`overlayCss` - the css applied to a div positioned on top of the content.
131
-
132
-
Here's an example using a `Button` element imported from elsewhere.
133
-
134
-
```tsx
135
-
<SplitPane
136
-
split="vertical"
137
-
collapseOptions={{
138
-
beforeToggleButton: <Button>⬅</Button>,
139
-
afterToggleButton: <Button>➡</Button>,
140
-
overlayCss: { backgroundColor: "black" },
141
-
buttonTransition: "zoom",
142
-
buttonPositionOffset: -20,
143
-
collapsedSize: 50,
144
-
collapseTransitionTimeout: 350,
145
-
}}
146
-
>
147
-
<div>This is a div</div>
148
-
<div>This is a second div</div>
149
-
<div>This is a third div</div>
150
-
<div>This is a fourth div</div>
151
-
</SplitPane>
152
-
```
153
-
154
-
**Note!**:eyes: When collapsing a panel, the `minSize` value is used to freeze the width of the collapsed panel to its minimum size and hides the rest of the content. This allows for a smooth collapse animation and is something to keep in mind. Until the animation reaches the min size it will shrink the panel as normal. Try it out for yourself!
95
+
Documentation can be found at https://collapse-pane.zurg.dev
155
96
97
+
If you notice an issue then please make an issue or a PR! All docs are generated from the `docs` folder in the master branch.
156
98
157
-
## Hooks and Saving State ⚡
158
99
159
-
The component manages its own state while resizing however also allows an initial state as well as callbacks to save state changes.
*`onDragStarted` fires as soon as you click down on a resizer and begin moving
169
-
*`onSaveSizes` fires when the movement of a resizer is finished and the mouse lifts **OR** when a panel is collapsed - as both of these trigger size changes.
170
-
*`onChange` fires on every size change, which can be **quite** often
171
-
*`onCollapse` fires whenever a panel is collapsed, and keeps track of the previously collapsed panes
172
-
173
-
The initial state is passed in with these three props:
174
-
175
-
```ts
176
-
initialSizes?:number[];
177
-
minSizes?:number|number[];
178
-
collapsedSizes?:Nullable<number>[];
179
-
```
180
-
*`initialSizes` is the default flex-basis that's given to the panes. This can be a simple ratio if it's the first time the render will happen and there's no saved sizes. e.g. `[1, 2, 1]` would make the second panel twice as big as its siblings. If you're saving state this should be the saved size value on a second render.
181
-
*`minSizes` is either (1) a minimum size that's given to **all** the panes, or (2) an array of minimum sizes that's given to each pane in order. Any missing sizes in the array will be assumed default.
182
-
*`collapsedSizes` an array of nullable numbers. This keeps track of a pane's size before it was collapsed. If not collapsed it's null. This will determine which panels are collapsed and what to do when they're uncollapsed.
183
-
184
-
Typically if this is a controlled component you would have state variables for `initialSizes` and `collapsedSizes` and have callbacks on `onSaveSizes` and `onCollapse` that would save the two data points and pass them back into the `SplitPane` on a remount. The `minSizes` would typically never change.
185
-
186
-
187
-
## RTL Support ( Arabic, Hebrew, Farsi ) 🕋
188
-
189
-
This library easily supports RTL languages by providing a `direction` prop. This is only necessary if you're using RTL and can be left out.
190
-
191
-
**Note!** 🚨 the `direction` is _only_ applicable if the split is `vertical`
192
-
193
-
e.g.
194
-
```tsx
195
-
<divstyle={{ direction: 'rtl' }}>
196
-
<SplitPane
197
-
split="vertical"
198
-
direction="rtl"
199
-
>
200
-
<div>اللوحة الأولى</div>
201
-
<div>اللوحة الثانية</div>
202
-
<div>اللوحة الثالثة</div>
203
-
<div>اللوحة الرابعة</div>
204
-
</SplitPane>
205
-
</div>
206
-
```
207
100
208
-
# Contributing and PRs 💖
101
+
# Contributing and PRs :sparkling_heart:
209
102
210
103
If you would like to contribute please check out the [contributor guide](/CONTRIBUTING.md)
211
104
212
105
All contributions are welcome! All issues and feature requests are welcome!
213
106
214
107
215
108
216
-
# Credit and Attribution 🙏
109
+
# Credit and Attribution :pray:
217
110
218
111
This project did not start off from scratch. The foundation of the project was the excellently written [react-multi-split-pane](https://github.com/neoraider/react-multi-split-pane) library which is itself a typescript rewrite of the [react-split-pane](https://github.com/tomkp/react-split-pane) library.
Copy file name to clipboardExpand all lines: docs/README.md
+11-12Lines changed: 11 additions & 12 deletions
Original file line number
Diff line number
Diff line change
@@ -3,15 +3,15 @@
3
3
This is intended to be **the** simple, reliable, configurable, and elegant solution to having splittable, draggable and collapsible panes in your React application.
4
4
5
5
6
-
## [[click for storybook demo]](https://react-collapse-pane.zurg.dev/)
6
+
## [[click for storybook demo]](https://storybook.collapse-pane.zurg.dev/)
7
7
8
-
# Getting Started :rocket:
8
+
# Getting Started 🚀
9
9
10
10
Install react-collapse-pane:
11
-
```bash
11
+
```sh
12
12
npm i --save-dev react-collapse-pane
13
13
```
14
-
```bash
14
+
```sh
15
15
yarn add --dev react-collapse-pane
16
16
```
17
17
@@ -25,7 +25,7 @@ If you're using Typescript the `SplitPaneProps`, as well as a few other helper t
This will split the children. The children can be any valid React child. If a child is `null` it will be excluded from being split or displayed.
47
47
48
-
**Note!**:eyes: There is no limit to the number of divs you have as children. The `SplitPane` will split them all accordingly.
48
+
?> **Note**there is no limit to the number of divs you have as children. The `SplitPane` will split them all accordingly.
49
49
50
50
## Styling the Resizer 💅
51
51
52
52
By default there is a 1px divider that starts out `rgba(120, 120, 120, 0.3)` and transitions to `rgba(120, 120, 120, 0.6)` on hover. Having a grey color with an alpha value means that it will look nice on both light and dark backgrounds.
53
53
54
54
This is easily replaceable with the `css` and `hoverCss` options. No need to worry about pseudo selectors, transitions, animations or anything. You just have to indicate what the divider should look like **before** and **after**. This is accomplished by having two separate divs, one of which fades out and the other which fades in.
55
55
56
-
**Note** 🚨 The css props must be valid `React.CSSProperties` objects.
56
+
!> **Note!** The css props must be valid `React.CSSProperties` objects.
57
57
58
58
The sizer also has a grabbable surface that spans the height (or length) of the split and has a default grabbable surface of `1rem`. This is changeable by the `grabberSize` option which can be set to any valid CSS size value for `width` or `height`.
59
59
60
-
**Note!**:eyes: As per default React CSS, a number will be interpreted as a `px` value.
60
+
?> As per default React CSS, a number will be interpreted as a `px` value.
61
61
62
62
63
63
Here's an example:
@@ -85,7 +85,7 @@ Here's an example:
85
85
86
86
## Using a Collapse Button 🤹♀️
87
87
88
-
This is the killer feature of this library :eyes:
88
+
!> This is the killer feature of this library :eyes:
89
89
90
90
It's a common UX need to want to collapse the left or initial panel to give more room for another part of a site or app. This is easily accomplished by including several `CollapseOptions` as a prop to the `SplitPane`.
91
91
@@ -121,7 +121,7 @@ Here's an example using a `Button` element imported from elsewhere.
121
121
</SplitPane>
122
122
```
123
123
124
-
**Note!**:eyes: When collapsing a panel, the `minSize` value is used to freeze the width of the collapsed panel to its minimum size and hides the rest of the content. This allows for a smooth collapse animation and is something to keep in mind. Until the animation reaches the min size it will shrink the panel as normal. Try it out for yourself!
124
+
?> **Note!**:eyes: When collapsing a panel, the `minSize` value is used to freeze the width of the collapsed panel to its minimum size and hides the rest of the content. This allows for a smooth collapse animation and is something to keep in mind. Until the animation reaches the min size it will shrink the panel as normal. Try it out for yourself!
125
125
126
126
127
127
## Hooks and Saving State ⚡
@@ -156,11 +156,10 @@ Typically if this is a controlled component you would have state variables for `
156
156
157
157
## RTL Support ( Arabic, Hebrew, Farsi ) 🕋
158
158
159
-
This library easily supports RTL languages by providing a `direction` prop. This is only necessary if you're using RTL and can be left out.
159
+
This library easily supports RTL languages by providing a `direction` prop. This is only necessary if you're using RTL.
160
160
161
161
**Note!** 🚨 the `direction` is _only_ applicable if the split is `vertical`
0 commit comments