141 lines
5.1 KiB
Plaintext
141 lines
5.1 KiB
Plaintext
# 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 (
|
|
<div style={{ height: "46rem" }}>
|
|
<Excalidraw>
|
|
<WelcomeScreen />
|
|
</Excalidraw>
|
|
</div>
|
|
);
|
|
}
|
|
```
|
|
|
|
You can also customize the welcome screen by passing children to the `WelcomeScreen` component. See below.
|
|
|
|
## <WelcomeScreen/>
|
|
|
|
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).
|
|
|
|
<img
|
|
src={require("@site/static/img/welcome-screen-overview.png").default}
|
|
alt="Excalidraw logo: Sketch handrawn like diagrams."
|
|
/>
|
|
|
|
### Center
|
|
|
|
`<WelcomeScreen.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 (
|
|
<div style={{ height: "500px" }}>
|
|
<Excalidraw>
|
|
<WelcomeScreen>
|
|
<WelcomeScreen.Center>
|
|
<WelcomeScreen.Center.Logo />
|
|
<WelcomeScreen.Center.Heading>
|
|
Welcome Screen Heading!
|
|
</WelcomeScreen.Center.Heading>
|
|
<WelcomeScreen.Center.Menu>
|
|
<WelcomeScreen.Center.MenuItemLink href="https://github.com/excalidraw/excalidraw">
|
|
Excalidraw GitHub
|
|
</WelcomeScreen.Center.MenuItemLink>
|
|
<WelcomeScreen.Center.MenuItemHelp />
|
|
</WelcomeScreen.Center.Menu>
|
|
</WelcomeScreen.Center>
|
|
</WelcomeScreen>
|
|
</Excalidraw>
|
|
</div>
|
|
);
|
|
}
|
|
```
|
|
|
|
#### Logo
|
|
|
|
Use the `<WelcomeScreen.Center.Logo/>` to render a logo. By default it renders the Excalidraw logo and name. Supply `children` to customize.
|
|
|
|
#### Heading
|
|
|
|
Use the `<WelcomeScreen.Center.Heading/>` to render a heading below the logo. Supply `children` to change the default message.
|
|
|
|
#### Menu
|
|
|
|
`<WelcomeScreen.Center.Menu/>` is a wrapper component for the menu items. You can build your menu using the `<WelcomeScreen.Center.MenuItem>` and `<WelcomeScreen.Center.MenuItemLink>` components, render your own, or render one of the default menu items.
|
|
|
|
The default menu items are:
|
|
|
|
- `<WelcomeScreen.Center.MenuItemHelp/>` - opens the help dialog.
|
|
|
|
- `<WelcomeScreen.Center.MenuItemLoadScene/>` - open the load file dialog.
|
|
|
|
- `<WelcomeScreen.Center.MenuItemLiveCollaborationTrigger/>` - intended to open the live collaboration dialog. Works similarly to [`<LiveCollaborationTrigger>`](/docs/@excalidraw/excalidraw/api/children-components/live-collaboration-trigger) and you must supply `onSelect()` handler to integrate with your collaboration implementation.
|
|
|
|
#### MenuItem
|
|
|
|
The `<WelcomeScreen.Center.MenuItem/>` 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 `<WelcomeScreen.Hints.*>` subcomponents render the UI hints. Text of each hint can be customized by supplying `children`.
|
|
|
|
```jsx live
|
|
function App() {
|
|
return (
|
|
<div style={{ height: "500px" }}>
|
|
<Excalidraw>
|
|
<WelcomeScreen>
|
|
<WelcomeScreen.Hints.ToolbarHint>
|
|
<p> ToolBar Hints </p>
|
|
</WelcomeScreen.Hints.ToolbarHint>
|
|
<WelcomeScreen.Hints.MenuHint />
|
|
<WelcomeScreen.Hints.HelpHint />
|
|
</WelcomeScreen>
|
|
</Excalidraw>
|
|
</div>
|
|
);
|
|
}
|
|
```
|
|
|
|
#### MenuHint
|
|
|
|
`<WelcomeScreen.Hints.MenuHint>` hint subcomponent for the main menu. Supply `children` to customize the hint text.
|
|
|
|
#### ToolbarHint
|
|
|
|
`<WelcomeScreen.Hints.ToolbarHint>` hint subcomponent for the toolbar. Supply `children` to customize the hint text.
|
|
|
|
#### Help
|
|
|
|
`<WelcomeScreen.Hints.Help>` hint subcomponent for the help dialog. Supply `children` to customize the hint text.
|