diff options
Diffstat (limited to 'dev-docs/docs/@excalidraw/excalidraw/api/children-components/sidebar.mdx')
| -rw-r--r-- | dev-docs/docs/@excalidraw/excalidraw/api/children-components/sidebar.mdx | 129 |
1 files changed, 129 insertions, 0 deletions
diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/children-components/sidebar.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/children-components/sidebar.mdx new file mode 100644 index 0000000..ed12f64 --- /dev/null +++ b/dev-docs/docs/@excalidraw/excalidraw/api/children-components/sidebar.mdx @@ -0,0 +1,129 @@ +# Sidebar + +The editor comes with a default sidebar on the right in LTR (Left to Right) mode which contains the library. You can also add your own custom sidebar(s) by rendering this component as a child of `<Excalidraw>`. + +## Props + +| Prop | Type | Required | Description | +| --- | --- | --- | --- | +| `name` | `string` | Yes | Sidebar name that uniquely identifies it. | +| `children` | `React.ReactNode` | Yes | Content you want to render inside the sidebar. | +| `onStateChange` | `(state: AppState["openSidebar"]) => void` | No | Invoked on open/close or tab change. No need to act on this event, as the editor manages the sidebar open state on its own. | +| `onDock` | `(docked: boolean) => void` | No | Invoked when the user toggles the `dock` button. Passed the current docked state. | +| `docked` | `boolean` | No | Indicates whether the sidebar is `docked`. By default, the sidebar is `undocked`. If passed, the docking becomes controlled. | +| `className` | `string` | No | | +| `style` | `React.CSSProperties` | No | | + +At minimum, each sidebar needs to have a unique `name` prop, and render some content inside it, which can be either composed from the exported sidebar sub-components, or custom elements. + +Unless `docked={true}` is passed, the sidebar will close when the user clicks outside of it. It can also be closed using the close button in the header, if you render the `<Sidebar.Header>` component. + +Further, if the sidebader doesn't comfortably fit in the editor, it won't be dockable. To decide the breakpoint for docking you can use [UIOptions.dockedSidebarBreakpoint](/docs/@excalidraw/excalidraw/api/props/ui-options#dockedsidebarbreakpoint). + +To make your sidebar user-dockable, you need to supply `props.docked` (current docked state) alongside `props.onDock` callback (to listen for and handle docked state changes). The component doesn't track local state for the `docked` prop, so you need to manage it yourself. + +## Sidebar.Header + +| Prop | Type | Required | Description | +| --- | --- | --- | --- | +| `children` | `React.ReactNode` | No | Content you want to render inside the sidebar header next to the `close` / `dock` buttons. | +| `className` | `string` | No | | + +Renders a sidebar header which contains a close button, and a dock button (when applicable). You can also render custom content in addition. + +Can be nested inside specific tabs, or rendered as direct child of `<Sidebar>` for the whole sidebar component. + +## Sidebar.Tabs + +| Prop | Type | Required | Description | +| ---------- | ----------------- | -------- | ------------------------------ | +| `children` | `React.ReactNode` | No | Container for individual tabs. | + +Sidebar may contain inner tabs. Each `<Sidebar.Tab>` must be rendered inside this `<Sidebar.Tabs>` container component. + +## Sidebar.Tab + +| Prop | Type | Required | Description | +| ---------- | ----------------- | -------- | ---------------- | +| `tab` | `string` | Yes | Unique tab name. | +| `children` | `React.ReactNode` | No | Tab content. | + +Content of a given sidebar tab. It must be rendered inside `<Sidebar.Tabs>`. + +## Sidebar.TabTriggers + +| Prop | Type | Required | Description | +| --- | --- | --- | --- | +| `children` | `React.ReactNode` | No | Container for individual tab triggers. | + +Container component for tab trigger buttons to switch between tabs. + +## Sidebar.TabTrigger + +| Prop | Type | Required | Description | +| --- | --- | --- | --- | +| `tab` | `string` | Yes | Tab name to toggle. | +| `children` | `React.ReactNode` | No | Tab trigger content, such as a label. | + +A given tab trigger button that switches to a given sidebar tab. It must be rendered inside `<Sidebar.TabTriggers>`. + +## Sidebar.Trigger + +| Prop | Type | Required | Description | +| --- | --- | --- | --- | +| `name` | `string` | Yes | Sidebar name the trigger will control. | +| `tab` | `string` | No | Optional tab to open. | +| `onToggle` | `(open: boolean) => void` | No | Callback invoked on toggle. | +| `title` | `string` | No | A11y title. | +| `children` | `React.ReactNode` | No | Content (usually label) you want to render inside the button. | +| `icon` | `JSX.Element` | No | Trigger icon if any. | +| `className` | `string` | No | | +| `style` | `React.CSSProperties` | No | | + +You can use the [`ref.toggleSidebar({ name: "custom" })`](/docs/@excalidraw/excalidraw/api/props/excalidraw-api#toggleSidebar) api to control the sidebar, but we export a trigger button to make UI use cases easier. + +## Example + +```tsx live +function App() { + const [docked, setDocked] = useState(false); + + return ( + <div style={{ height: "580px" }}> + <Excalidraw + UIOptions={{ + // this effectively makes the sidebar dockable on any screen size, + // ignoring if it fits or not + dockedSidebarBreakpoint: 0, + }} + > + <Sidebar name="custom" docked={docked} onDock={setDocked}> + <Sidebar.Header /> + <Sidebar.Tabs style={{ padding: "0.5rem" }}> + <Sidebar.Tab tab="one">Tab one!</Sidebar.Tab> + <Sidebar.Tab tab="two">Tab two!</Sidebar.Tab> + <Sidebar.TabTriggers> + <Sidebar.TabTrigger tab="one">One</Sidebar.TabTrigger> + <Sidebar.TabTrigger tab="two">Two</Sidebar.TabTrigger> + </Sidebar.TabTriggers> + </Sidebar.Tabs> + </Sidebar> + + <Footer> + <Sidebar.Trigger + name="custom" + tab="one" + style={{ + marginLeft: "0.5rem", + background: "#70b1ec", + color: "white", + }} + > + Toggle Custom Sidebar + </Sidebar.Trigger> + </Footer> + </Excalidraw> + </div> + ); +} +``` |