Skip to content

Virtual whiteboard for sketching hand-drawn like diagrams

docs: new Sidebar API (#6976)

David Luzara34216f9fcb0
diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/children-components/children-components-intro.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/children-components/children-components-intro.mdx
index 706adb594c..06bb1cbaf6 100644
--- a/dev-docs/docs/@excalidraw/excalidraw/api/children-components/children-components-intro.mdx
+++ b/dev-docs/docs/@excalidraw/excalidraw/api/children-components/children-components-intro.mdx
@@ -17,5 +17,6 @@ Below are the currently supported components:
- [MainMenu](/docs/@excalidraw/excalidraw/api/children-components/main-menu)
- [WelcomeScreen](/docs/@excalidraw/excalidraw/api/children-components/welcome-screen)
+- [Sidebar](/docs/@excalidraw/excalidraw/api/children-components/sidebar)
- [Footer](/docs/@excalidraw/excalidraw/api/children-components/footer)
- [LiveCollaborationTrigger](/docs/@excalidraw/excalidraw/api/children-components/live-collaboration-trigger)
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 0000000000..08445a1c34
--- /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/ref#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>
+ );
+}
+```
diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/props/props.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/props/props.mdx
index 104d9dccd4..5764528b61 100644
--- a/dev-docs/docs/@excalidraw/excalidraw/api/props/props.mdx
+++ b/dev-docs/docs/@excalidraw/excalidraw/api/props/props.mdx
@@ -17,7 +17,6 @@ All `props` are *optional*.
| [`langCode`](#langcode) | `string` | `en` | Language code string to be used in Excalidraw |
| [`renderTopRightUI`](/docs/@excalidraw/excalidraw/api/props/render-props#rendertoprightui) | `function` | _ | Render function that renders custom UI in top right corner |
| [`renderCustomStats`](/docs/@excalidraw/excalidraw/api/props/render-props#rendercustomstats) | `function` | _ | Render function that can be used to render custom stats on the stats dialog. |
-| [`renderSidebar`](/docs/@excalidraw/excalidraw/api/props/render-props#rendersidebar) | `function` | _ | Render function that renders custom sidebar. |
| [`viewModeEnabled`](#viewmodeenabled) | `boolean` | _ | This indicates if the app is in `view` mode. |
| [`zenModeEnabled`](#zenmodeenabled) | `boolean` | _ | This indicates if the `zen` mode is enabled |
| [`gridModeEnabled`](#gridmodeenabled) | `boolean` | _ | This indicates if the `grid` mode is enabled |
diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/props/ref.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/props/ref.mdx
index eaf58f758e..6edcc9b9e9 100644
--- a/dev-docs/docs/@excalidraw/excalidraw/api/props/ref.mdx
+++ b/dev-docs/docs/@excalidraw/excalidraw/api/props/ref.mdx
@@ -404,15 +404,15 @@ This API can be used to customise the mouse cursor on the canvas and has the bel
(cursor: string) => void
```
-## toggleMenu
+## toggleSidebar
```tsx
-(type: "library" | "customSidebar", force?: boolean) => boolean;
+(opts: { name: string; tab?: string; force?: boolean }) => boolean;
```
-This API can be used to toggle a specific menu (currently only the sidebars), and returns whether the menu was toggled on or off. If the `force` flag passed, it will force the menu to be toggled either on/off based on the `boolean` passed.
+This API can be used to toggle sidebar, optionally opening a specific sidebar tab. It returns whether the sidebar was toggled on or off. If the `force` flag passed, it will force the sidebar to be toggled either on/off.
-This API is especially useful when you render a custom sidebar using [`renderSidebar`](#rendersidebar) prop, and you want to toggle it from your app based on a user action.
+This API is especially useful when you render a custom [`<Sidebar/>`](/docs/@excalidraw/excalidraw/api/children-components/sidebar), and you want to toggle it from your app based on a user action.
## resetCursor
diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/props/render-props.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/props/render-props.mdx
index 5256704c20..f0f4adc449 100644
--- a/dev-docs/docs/@excalidraw/excalidraw/api/props/render-props.mdx
+++ b/dev-docs/docs/@excalidraw/excalidraw/api/props/render-props.mdx
@@ -6,8 +6,7 @@
(isMobile: boolean, appState:
<a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L95">
AppState
- </a>
- ) => JSX | null
+ </a>) => JSX | null
</pre>
A function returning `JSX` to render `custom` UI in the top right corner of the app.
@@ -63,69 +62,14 @@ function App() {
}
```
-## renderSidebar
-
-```tsx
-() => JSX | null;
-```
-
-You can render `custom sidebar` using this prop. This sidebar is the same that the library menu sidebar is using, and can be used for any purposes your app needs.
-
-You need to import the `Sidebar` component from `excalidraw` package and pass your content as its `children`. The function `renderSidebar` should return the `Sidebar` instance.
-
-### Sidebar
-The `<Sidebar>` component takes these props (all are optional except `children`):
-
-| Prop | Type | Description |
-| --- | --- | --- |
-| `children` | `React.ReactNode` | Content you want to render inside the `sidebar`. |
-| `onClose` | `function` | Invoked when the component is closed (by user, or the editor). No need to act on this event, as the editor manages the sidebar open state on its own. |
-| `onDock` | `function` | Invoked when the user toggles the `dock` button. The callback receives a `boolean` parameter `isDocked` which indicates whether the sidebar is `docked` |
-| `docked` | `boolean` | Indicates whether the sidebar is`docked`. By default, the sidebar is `undocked`. If passed, the docking becomes controlled, and you are responsible for updating the `docked` state by listening on `onDock` callback. To decide the breakpoint for docking you can use [UIOptions.dockedSidebarBreakpoint](/docs/@excalidraw/excalidraw/api/props/ui-options#dockedsidebarbreakpoint) for more info on docking. |
-| `dockable` | `boolean` | Indicates whether to show the `dock` button so that user can `dock` the sidebar. If `false`, you can still dock programmatically by passing `docked` as `true`. |
-
-The sidebar will always include a header with `close / dock` buttons (when applicable).
-You can also add custom content to the header, by rendering `<Sidebar.Header>` as a child of the `<Sidebar>` component. Note that the custom header will still include the default buttons.
-
-
-### Sidebar.Header
-
-| name | type | description |
-| --- | --- | --- |
-| children | `React.ReactNode` | Content you want to render inside the sidebar header as a sibling of `close` / `dock` buttons. |
-
-To control the visibility of the sidebar you can use [`toggleMenu("customSidebar")`](/docs/@excalidraw/excalidraw/api/props/ref#togglemenu) api available via `ref`.
-
-```tsx live
-function App() {
- const [excalidrawAPI, setExcalidrawAPI] = useState(null);
-
- return (
- <div style={{ height: "500px" }}>
- <button className="custom-button" onClick={() => excalidrawAPI.toggleMenu("customSidebar")}>
- Toggle Custom Sidebar
- </button>
- <Excalidraw
- UIOptions={{ dockedSidebarBreakpoint: 100 }}
- ref={(api) => setExcalidrawAPI(api)}
- renderSidebar={() => {
- return (
- <Sidebar dockable={true}>
- <Sidebar.Header>Custom Sidebar Header </Sidebar.Header>
- <p style={{ padding: "1rem" }}> custom Sidebar Content </p>
- </Sidebar>
- );
- }}
- />
- </div>
- );
-}
-```
-
## renderEmbeddable
<pre>
- (element: NonDeleted&lt;ExcalidrawEmbeddableElement&gt;, appState: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L95">AppState</a>) => JSX.Element | null
+ (element: NonDeleted&lt;ExcalidrawEmbeddableElement&gt;, appState:{" "}
+ <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L95">
+ AppState
+ </a>
+ ) => JSX.Element | null
</pre>
Allows you to replace the renderer for embeddable elements (which renders `<iframe>` elements).
diff --git a/dev-docs/package.json b/dev-docs/package.json
index cbf0d4334f..bef57d76e7 100644
--- a/dev-docs/package.json
+++ b/dev-docs/package.json
@@ -18,7 +18,7 @@
"@docusaurus/core": "2.2.0",
"@docusaurus/preset-classic": "2.2.0",
"@docusaurus/theme-live-codeblock": "2.2.0",
- "@excalidraw/excalidraw": "0.15.3",
+ "@excalidraw/excalidraw": "0.15.2-6546-3398d86",
"@mdx-js/react": "^1.6.22",
"clsx": "^1.2.1",
"docusaurus-plugin-sass": "0.2.3",
diff --git a/dev-docs/sidebars.js b/dev-docs/sidebars.js
index 4ff33746b7..86356aeff5 100644
--- a/dev-docs/sidebars.js
+++ b/dev-docs/sidebars.js
@@ -64,6 +64,7 @@ const sidebars = {
items: [
"@excalidraw/excalidraw/api/children-components/main-menu",
"@excalidraw/excalidraw/api/children-components/welcome-screen",
+ "@excalidraw/excalidraw/api/children-components/sidebar",
"@excalidraw/excalidraw/api/children-components/footer",
"@excalidraw/excalidraw/api/children-components/live-collaboration-trigger",
],
diff --git a/dev-docs/yarn.lock b/dev-docs/yarn.lock
index a2b61d255f..3ef8a91904 100644
--- a/dev-docs/yarn.lock
+++ b/dev-docs/yarn.lock
@@ -1631,10 +1631,10 @@
url-loader "^4.1.1"
webpack "^5.73.0"
-"@excalidraw/[email protected]":
- version "0.15.3"
- resolved "https://registry.yarnpkg.com/@excalidraw/excalidraw/-/excalidraw-0.15.3.tgz#5dea570f76451adf68bc24d4bfdd67a375cfeab1"
- integrity sha512-/gpY7fgMO/AEaFLWnPqzbY8H7ly+/zocFf7D0Is5sWNMD2mhult5tana12lXKLSJ6EAz7ubo1A7LajXzvJXJDA==
+"@excalidraw/[email protected]":
+ version "0.15.2-6546-3398d86"
+ resolved "https://registry.yarnpkg.com/@excalidraw/excalidraw/-/excalidraw-0.15.2-6546-3398d86.tgz#e74d5ad944b8b414924d27ee91469a32b4f08dbf"
+ integrity sha512-Tzq6qighJUytXRA8iMzQ8onoGclo9CuvPSw7DMvPxME8nxAxn5CeK/gsxIs3zwooj9CC6XF42BSrx0+n+fPxaQ==
"@hapi/hoek@^9.0.0":
version "9.3.0"