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/
---
.../children-components-intro.mdx | 22 +++
.../excalidraw/api/children-components/footer.mdx | 68 +++++++++
.../live-collaboration-trigger.mdx | 62 ++++++++
.../api/children-components/main-menu.mdx | 169 +++++++++++++++++++++
.../excalidraw/api/children-components/sidebar.mdx | 129 ++++++++++++++++
.../api/children-components/welcome-screen.mdx | 140 +++++++++++++++++
6 files changed, 590 insertions(+)
create mode 100644 dev-docs/docs/@excalidraw/excalidraw/api/children-components/children-components-intro.mdx
create mode 100644 dev-docs/docs/@excalidraw/excalidraw/api/children-components/footer.mdx
create mode 100644 dev-docs/docs/@excalidraw/excalidraw/api/children-components/live-collaboration-trigger.mdx
create mode 100644 dev-docs/docs/@excalidraw/excalidraw/api/children-components/main-menu.mdx
create mode 100644 dev-docs/docs/@excalidraw/excalidraw/api/children-components/sidebar.mdx
create mode 100644 dev-docs/docs/@excalidraw/excalidraw/api/children-components/welcome-screen.mdx
(limited to 'dev-docs/docs/@excalidraw/excalidraw/api/children-components')
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
new file mode 100644
index 0000000..06bb1cb
--- /dev/null
+++ b/dev-docs/docs/@excalidraw/excalidraw/api/children-components/children-components-intro.mdx
@@ -0,0 +1,22 @@
+---
+sidebar_label: Children Components
+slug: /@excalidraw/excalidraw/api/children-components
+---
+
+# `` children
+
+We expose several components you can render as children of the `` component to customize the UI.
+
+:::info
+
+We have only recently started migrating to this type of component API. Some UI components are still using render props, and some UI customization isn't supported yet (such as the toolbar or the element properties panel). Stay tuned for more updates!
+
+:::
+
+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/footer.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/children-components/footer.mdx
new file mode 100644
index 0000000..3831268
--- /dev/null
+++ b/dev-docs/docs/@excalidraw/excalidraw/api/children-components/footer.mdx
@@ -0,0 +1,68 @@
+# Footer
+
+Earlier we were using `renderFooter` prop to render custom footer which was removed in [#5970](https://github.com/excalidraw/excalidraw/pull/5970). Now you can pass a `Footer` component instead to render the custom UI for footer.
+
+You will need to import the `Footer` component from the package and wrap your component with the Footer component. The `Footer` should a valid React Node.
+
+**Usage**
+
+```jsx live
+function App() {
+ return (
+
+
+
+
+
+ );
+}
+```
+
+This will only for `Desktop` devices.
+
+For `mobile` you will need to render it inside the [MainMenu](#mainmenu). You can use the [`useDevice`](#useDevice) hook to check the type of device, this will be available only inside the `children` of `Excalidraw` component.
+
+Open the `Menu` in the below playground and you will see the `custom footer` rendered.
+
+```jsx live noInline
+const MobileFooter = ({}) => {
+ const device = useDevice();
+ if (device.editor.isMobile) {
+ return (
+
+ );
+ }
+ return null;
+};
+
+const App = () => (
+
+
+
+ Item1
+ Item 2
+
+
+
+
+);
+
+// Need to render when code is span across multiple components
+// in Live Code blocks editor
+render();
+```
\ No newline at end of file
diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/children-components/live-collaboration-trigger.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/children-components/live-collaboration-trigger.mdx
new file mode 100644
index 0000000..ef74d0e
--- /dev/null
+++ b/dev-docs/docs/@excalidraw/excalidraw/api/children-components/live-collaboration-trigger.mdx
@@ -0,0 +1,62 @@
+# LiveCollaborationTrigger
+
+If you implement live collaboration support and want to expose the same UI button as on [excalidraw.com](https://excalidraw.com), you can render the `` component using the [renderTopRightUI](/docs/@excalidraw/excalidraw/api/props#rendertoprightui) prop.
+
+You'll need to supply `onSelect()` to handle opening of your collaboration dialog, but the button will display `appState.collaborators` count provided you have supplied it.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `onSelect` | `function` | Yes | | Handler called when the user clicks on the button |
+| `isCollaborating` | `boolean` | Yes | false | Whether live collaboration session is in effect. Modifies button style. |
+
+```tsx live
+function App() {
+ const [excalidrawAPI, setExcalidrawAPI] = useState(null);
+ const [isCollaborating, setIsCollaborating] = useState(false);
+ return (
+
+
+ Selecting the checkbox to see the collaborator count
+
+ );
+}
+```
diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/children-components/main-menu.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/children-components/main-menu.mdx
new file mode 100644
index 0000000..b0062d9
--- /dev/null
+++ b/dev-docs/docs/@excalidraw/excalidraw/api/children-components/main-menu.mdx
@@ -0,0 +1,169 @@
+# MainMenu
+
+By default Excalidraw will render the `MainMenu` with default options. If you want to customise the `MainMenu`, you can pass the `MainMenu` component with the list options.
+
+**Usage**
+
+```jsx live
+function App() {
+ return (
+
+ );
+}
+```
+
+### ``
+
+This is the `MainMenu` component. If you render it, you will need to populate the menu with your own items as we will not render any ourselves at that point.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | :-: | :-: | --- |
+| `onSelect` | `function` | No | - | Triggered when any item is selected (via mouse). Calling `event.preventDefault()` will stop menu from closing. |
+
+### MainMenu.Item
+
+To render an item, its recommended to use `MainMenu.Item`.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | :-: | :-: | --- |
+| `onSelect` | `function` | Yes | - | Triggered when selected (via mouse). Calling `event.preventDefault()` will stop menu from closing. |
+| `selected` | `boolean` | No | `false` | Whether item is active |
+| `children` | `React.ReactNode` | Yes | - | The content of the menu item |
+| `icon` | `JSX.Element` | No | - | The icon used in the menu item |
+| `shortcut` | `string` | No | - | The shortcut to be shown for the menu item |
+
+### MainMenu.ItemLink
+
+To render an item as a link, its recommended to use `MainMenu.ItemLink`.
+
+**Usage**
+
+```jsx live
+function App() {
+ return (
+
+
+
+
+ Google
+
+
+ Excalidraw
+
+
+
+
+ );
+}
+```
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | :-: | :-: | --- |
+| `onSelect` | `function` | No | - | Triggered when selected (via mouse). Calling `event.preventDefault()` will stop menu from closing. |
+| `selected` | `boolean` | No | `false` | Whether item is active |
+| `href` | `string` | Yes | - | The `href` attribute to be added to the `anchor` element. |
+| `children` | `React.ReactNode` | Yes | - | The content of the menu item |
+| `icon` | `JSX.Element` | No | - | The icon used in the menu item |
+| `shortcut` | `string` | No | - | The shortcut to be shown for the menu item |
+
+### MainMenu.ItemCustom
+
+To render a custom item, you can use `MainMenu.ItemCustom`.
+
+**Usage**
+
+```jsx live
+function App() {
+ return (
+
+
+
+
+
+
+
+
+
+ );
+}
+```
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | :-: | :-: | --- |
+| `children` | `React.ReactNode` | Yes | - | The content of the menu item |
+
+### MainMenu.DefaultItems
+
+For the items which are shown in the menu in [excalidraw.com](https://excalidraw.com), you can use `MainMenu.DefaultItems`
+
+```jsx live
+function App() {
+ return (
+
+ );
+}
+```
+
+Here is a [complete list](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/components/main-menu/DefaultItems.tsx) of the default items.
+
+### MainMenu.Group
+
+To Group item in the main menu, you can use `MainMenu.Group`
+
+```jsx live
+function App() {
+ return (
+
+ );
+}
+```
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | :-: | :-: | --- |
+| `children ` | `React.ReactNode` | Yes | - | The content of the `Menu Group` |
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 (
+
+ );
+}
+```
diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/children-components/welcome-screen.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/children-components/welcome-screen.mdx
new file mode 100644
index 0000000..8834870
--- /dev/null
+++ b/dev-docs/docs/@excalidraw/excalidraw/api/children-components/welcome-screen.mdx
@@ -0,0 +1,140 @@
+# WelcomeScreen
+
+When the canvas is empty, Excalidraw can show a welcome _splash_ screen with a logo, a few quick action items, and hints explaining what some of the UI buttons do. Once the user picks a tool, or has created an element on the canvas, the welcome screen will disappear.
+
+You can enable this behavior by rendering a `WelcomeScreen` component like this:
+
+```jsx live
+function App() {
+ return (
+
+
+
+
+
+ );
+}
+```
+
+You can also customize the welcome screen by passing children to the `WelcomeScreen` component. See below.
+
+##
+
+This is the main component. If you render it without any children, we will render the default welcome screen.
+
+You can customize which welcome screen subcomponents are rendered by passing them as children.
+
+The welcome screen consists of two main groups of subcomponents:
+
+1. [WelcomeScreen.Center](#welcomescreencenterlogo).
+2. [WeelcomeScreen.Hints](#welcomescreenhints).
+
+
+
+### Center
+
+`` subcomponent is the center piece of the welcome screen, containing the `logo`, `heading`, and `menu`. All three subcomponents are optional, and you can render whatever you wish into the center component.
+
+```jsx live
+function App() {
+ return (
+
+ );
+}
+```
+
+#### Logo
+
+Use the `` to render a logo. By default it renders the Excalidraw logo and name. Supply `children` to customize.
+
+#### Heading
+
+Use the `` to render a heading below the logo. Supply `children` to change the default message.
+
+#### Menu
+
+`` is a wrapper component for the menu items. You can build your menu using the `` and `` components, render your own, or render one of the default menu items.
+
+The default menu items are:
+
+- `` - opens the help dialog.
+
+- `` - open the load file dialog.
+
+- `` - intended to open the live collaboration dialog. Works similarly to [``](/docs/@excalidraw/excalidraw/api/children-components/live-collaboration-trigger) and you must supply `onSelect()` handler to integrate with your collaboration implementation.
+
+#### MenuItem
+
+The `` component can be used to render a menu item.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `onSelect` | `function` | Yes | | The handler is triggered when the item is selected. |
+| `children` | `React.ReactNode` | Yes | | The content of the menu item |
+| `icon` | `JSX.Element` | No | | The icon used in the menu item |
+| `shortcut` | `string` | No | | The keyboard shortcut (label-only, does not affect behavior) |
+
+**WelcomeScreen.Center.MenuItemLink**
+
+To render an external link in a menu item, you can use this component.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `href` | `string` | Yes | | The `href` attribute to be added to the `anchor` element. |
+| `children` | `React.ReactNode` | Yes | | The content of the menu item |
+| `icon` | `JSX.Element` | No | | The icon used in the menu item |
+| `shortcut` | `string` | No | | The keyboard shortcut (label-only, does not affect behavior) |
+
+### Hints
+
+These `` subcomponents render the UI hints. Text of each hint can be customized by supplying `children`.
+
+```jsx live
+function App() {
+ return (
+
+
+
+
+
ToolBar Hints
+
+
+
+
+
+
+ );
+}
+```
+
+#### MenuHint
+
+`` hint subcomponent for the main menu. Supply `children` to customize the hint text.
+
+#### ToolbarHint
+
+`` hint subcomponent for the toolbar. Supply `children` to customize the hint text.
+
+#### Help
+
+`` hint subcomponent for the help dialog. Supply `children` to customize the hint text.
--
cgit v1.2.3
![Excalidraw logo: Sketch hand-drawn like diagrams.]({require("@site/static/img/welcome-screen-overview.png").default})
+
+### Center
+
+`