From bc297e5e496d9f48ef77581b7fb41fdf328a62cf Mon Sep 17 00:00:00 2001 From: kj_sh604 Date: Sun, 15 Mar 2026 16:19:35 -0400 Subject: refactor: dev-docs/ --- .../excalidraw/api/children-components/sidebar.mdx | 129 +++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 dev-docs/docs/@excalidraw/excalidraw/api/children-components/sidebar.mdx (limited to 'dev-docs/docs/@excalidraw/excalidraw/api/children-components/sidebar.mdx') 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 ``. + +## 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 `` 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 `` 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 `` must be rendered inside this `` 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.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.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 ( +
+ + + + + Tab one! + Tab two! + + One + Two + + + + + + +
+ ); +} +``` -- cgit v1.2.3