# SidePanel
Renders a side panel with an overlay over the app.
## Usage
```jsx
function App() {
const [opened, setOpened] = useState(false)
return (
Sidepanel content goes here.
)
}
```
## Demonstration
## Props
#### `children`
| TYPE | DEFAULT VALUE |
| ------------ | --------------- |
| `React node` | None (required) |
The content of the sidepanel.
#### `title`
| TYPE | DEFAULT VALUE |
| ------------ | --------------- |
| `React node` | None (required) |
The main title for the panel.
#### `opened`
| TYPE | DEFAULT VALUE |
| --------- | ------------- |
| `Boolean` | `true` |
Toggles the visibility of the panel. Note: when the panel finishes closing, the children components will get unmounted.
#### `onClose`
| TYPE | DEFAULT VALUE |
| ---------- | ------------- |
| `Function` | None |
Gets called when the user tries to close the panel, by clicking on the close button or the overlay.
#### `blocking`
| TYPE | DEFAULT VALUE |
| --------- | ------------- |
| `Boolean` | `false` |
When set, removes the ability to close the panel by using the close button or the overlay.
## Related hooks
#### useSidePanel()
This hook should be used inside `SidePanel`, and returns an object with two entries:
* `status` represents the current state of the panel: `opened`, `closed`, `opening`, `closing`.
* `readyToFocus` can be used to focus an element as soon as possible inside the panel without affecting the transition.
About the need to have `readyToFocus`: browser engines tend to force newly focused elements to move inside the viewport, skipping current transitions in the process. `readyToFocus` detects that the transition is half way, which is generally a safe point to start focusing an element without any transition issue. If you still notice a transition issue, another option is to use `status === 'opened'`.
#### **Example**
```jsx
// MySidePanel.js
function MySidePanel() {
const inputRef = useRef()
const { readyToFocus } = useSidePanel()
useEffect(() => {
if (readyToFocus && inputRef.current) {
inputRef.current.focus()
}
}, [readyToFocus, inputRef])
// The TextInput will get focused as soon as possible.
return
}
export default props => (
)
```
And because calling `.focus()` on a reference is a very common use case, another hook is provided to do it easily: `useSidePanelFocusOnReady()`.
#### useSidePanelFocusOnReady()
This hook can be used to focus a ref (usually a `TextInput`) when `readyToFocus` is set to `true`.
It takes a React ref as a parameter, or creates one if not provided. It returns this ref.
This is how `useSidePanelFocusOnReady()` can be used:
```jsx
// MySidePanel.js
function MySidePanel() {
const inputRef = useSidePanelFocusOnReady()
// The TextInput will get focused as soon as possible.
return
}
export default props => (
)
```