You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
140 lines
5.1 KiB
140 lines
5.1 KiB
# 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.
|
|
|