@douyinfe/semi-ui
Version:
A modern, comprehensive, flexible design system and UI library. Connect DesignOps & DevOps. Quickly build beautiful React apps. Maintained by Douyin-fe team.
553 lines (518 loc) • 19.8 kB
Markdown
---
localeCode: en-US
order: 85
category: Show
title: UserGuide
icon: doc-userGuide
brief: Used to guide new users through pages
---
## Demos
### How to import
```jsx import
import { UserGuide } from '@douyinfe/semi-ui';
```
### Basic Usage
```jsx live=true
import React from 'react';
import { UserGuide, Button, Space, Tag, Switch } from '@douyinfe/semi-ui';
() => {
const [visible, setVisible] = useState(false);
const showDialog = () => {
setVisible(true);
};
return (
<div>
<Button onClick={showDialog}>Start Guide</Button>
<br />
<br />
<Space>
<Switch id={'basic-demo-1'} defaultChecked={true}></Switch>
<Tag id={'basic-demo-2'}> Default Tag </Tag>
<Button id={'basic-demo-3'}>Confirm</Button>
</Space>
<UserGuide
mode="popup"
mask={true}
visible={visible}
steps={[
{
target: document.querySelector('#basic-demo-1'),
title: "Beginner's Guide",
description: 'Hello ByteDancer!',
position: 'bottom',
},
{
target: document.querySelector('#basic-demo-2'),
title: 'Switch',
description: 'This is a Semi Switch',
position: 'bottom',
},
{
target: document.querySelector('#basic-demo-3'),
title: 'Button',
description: 'This is a Semi Button',
position: 'bottom',
},
]}
onChange={(current) => {
console.log('Current guide step', current);
}}
onNext={(current) => {
console.log('Next guide step');
}}
onPrev={(current) => {
console.log('Previous guide step');
}}
onFinish={() => {
setVisible(false);
console.log('Guide completed');
}}
onSkip={() => {
setVisible(false);
console.log('Skip guide');
}}
/>
</div>
);
};
```
### Theme
`popup` bubble card mode provides two themes `default` and `primary`, set by the `theme` property.
```jsx live=true
import React from 'react';
import { UserGuide, Button, Space, Tag, Switch } from '@douyinfe/semi-ui';
() => {
const [visible, setVisible] = useState(false);
const showDialog = () => {
setVisible(true);
};
return (
<div>
<Button onClick={showDialog}>Start Guide</Button>
<br />
<br />
<Space>
<Switch id={'theme-demo-1'} defaultChecked={true}></Switch>
<Tag id={'theme-demo-2'}> Default Tag </Tag>
<Button id={'theme-demo-3'}>Confirm</Button>
</Space>
<UserGuide
mode="popup"
mask={true}
visible={visible}
theme="primary"
steps={[
{
target: document.querySelector('#theme-demo-1'),
title: "Beginner's Guide",
description: 'Hello ByteDancer!',
position: 'bottom',
},
{
target: document.querySelector('#theme-demo-2'),
title: 'Switch',
description: 'This is a Semi Switch',
position: 'bottom',
},
{
target: document.querySelector('#theme-demo-3'),
title: 'Button',
description: 'This is a Semi Button',
position: 'bottom',
},
]}
onFinish={() => {
setVisible(false);
console.log('引导完成');
}}
onSkip={() => {
setVisible(false);
console.log('跳过引导');
}}
/>
</div>
);
};
```
### Popup position
`popup` bubble card mode provides 12 positions, optional values are `top`, `topLeft`, `topRight`, `left`, `leftTop`, `leftBottom`, `right`, `rightTop`, `rightBottom`, `bottom`, `bottomLeft`, `bottomRight`, and can be set by the `showArrow` property to display the arrow.
```jsx live=true
import React from 'react';
import { UserGuide, Button, Space, Tag, Switch } from '@douyinfe/semi-ui';
() => {
const [visible, setVisible] = useState(false);
const showDialog = () => {
setVisible(true);
};
return (
<div>
<Button id={'position-demo'} onClick={showDialog}>Start Guide</Button>
<UserGuide
mode="popup"
mask={true}
visible={visible}
steps={[
{
target: document.querySelector('#position-demo'),
title: "Beginner's Guide",
description: 'Hello ByteDancer!',
position: 'top',
},
{
target: document.querySelector('#position-demo'),
title: 'New Position',
description: 'This is Right Position',
position: 'right',
},
{
target: document.querySelector('#position-demo'),
title: 'Hide Arrow',
description: 'We hide the arrow',
position: 'bottom',
showArrow: false,
},
]}
onFinish={() => {
setVisible(false);
console.log('Guide completed');
}}
onSkip={() => {
setVisible(false);
console.log('Skip guide');
}}
/>
</div>
);
};
```
### Set the size of the highlight area
Set by the `spotlightPadding` property.
```jsx live=true
import React from 'react';
import { UserGuide, Button, Space, Tag, Switch } from '@douyinfe/semi-ui';
() => {
const [visible, setVisible] = useState(false);
const showDialog = () => {
setVisible(true);
};
return (
<div>
<Button onClick={showDialog}>Start Guide</Button>
<br />
<br />
<Space>
<Switch id={'padding-demo-1'} defaultChecked={true}></Switch>
<Tag id={'padding-demo-2'}> Default Tag </Tag>
<Button id={'padding-demo-3'}>Confirm</Button>
</Space>
<UserGuide
mode="popup"
mask={true}
visible={visible}
spotlightPadding={10}
steps={[
{
target: document.querySelector('#padding-demo-1'),
title: "Beginner's Guide",
description: 'Hello ByteDancer!',
},
{
target: document.querySelector('#padding-demo-2'),
title: 'New Padding',
description: 'This is 10px padding',
},
{
target: document.querySelector('#padding-demo-3'),
title: 'Change Padding',
spotlightPadding: 15,
description: 'We change the Padding to 15px',
},
]}
onFinish={() => {
setVisible(false);
console.log('Guide completed');
}}
onSkip={() => {
setVisible(false);
console.log('Skip guide');
}}
/>
</div>
);
};
```
### Customize the button
Set by the `nextButtonProps` and `prevButtonProps` properties.
```jsx live=true
import React from 'react';
import { UserGuide, Button, Space, Tag, Switch } from '@douyinfe/semi-ui';
() => {
const [visible, setVisible] = useState(false);
const showDialog = () => {
setVisible(true);
};
return (
<div>
<Button onClick={showDialog}>Start Guide</Button>
<br />
<br />
<Space>
<Switch id={'button-demo-1'} defaultChecked={true}></Switch>
<Tag id={'button-demo-2'}> Default Tag </Tag>
<Button id={'button-demo-3'}>Confirm</Button>
</Space>
<UserGuide
mode="popup"
mask={true}
visible={visible}
nextButtonProps={{
children: 'Next',
}}
prevButtonProps={{
children: 'Prev',
theme: 'borderless',
}}
finishText="I know!"
steps={[
{
target: document.querySelector('#button-demo-1'),
title: "Beginner's Guide",
description: 'Hello ByteDancer!',
},
{
target: document.querySelector('#button-demo-2'),
title: 'New Button Style',
description: 'Button text is Next',
},
{
target: document.querySelector('#button-demo-3'),
title: 'New finish button text',
description: 'Button text is I know',
},
]}
onFinish={() => {
setVisible(false);
console.log('Guide completed');
}}
onSkip={() => {
setVisible(false);
console.log('Skip guide');
}}
/>
</div>
);
};
```
### Controlled
Set by the `current` property.
```jsx live=true
import React from 'react';
import { UserGuide, Button, Space, Tag, Switch } from '@douyinfe/semi-ui';
() => {
const [visible, setVisible] = useState(false);
const [current, setCurrent] = useState(0);
const showDialog = () => {
setVisible(true);
};
return (
<div>
<Button onClick={showDialog}>Start Guide</Button>
<br />
<br />
<Space>
<Switch id={'controlled-demo-1'} defaultChecked={true}></Switch>
<Tag id={'controlled-demo-2'}> Default Tag </Tag>
<Button id={'controlled-demo-3'}>Confirm</Button>
</Space>
<UserGuide
mode="popup"
mask={true}
visible={visible}
current={current}
steps={[
{
target: document.querySelector('#controlled-demo-1'),
title: "Beginner's Guide",
description: 'Hello ByteDancer!',
position: 'bottom',
},
{
target: document.querySelector('#controlled-demo-2'),
title: 'Switch',
description: 'This is a Semi Switch',
position: 'bottom',
},
{
target: document.querySelector('#controlled-demo-3'),
title: 'Button',
description: 'This is a Semi Button',
position: 'bottom',
},
]}
onChange={(current) => {
setCurrent(current);
}}
onFinish={() => {
setVisible(false);
setCurrent(0);
console.log('Guide completed');
}}
onSkip={() => {
setVisible(false);
setCurrent(0);
console.log('Skip guide');
}}
/>
</div>
);
};
```
### Modal guide
Set by the `mode` property.
```jsx live=true
import React from 'react';
import { UserGuide, Button, Space, Tag, Switch, Image, Typography } from '@douyinfe/semi-ui';
() => {
const [visible, setVisible] = useState(false);
const showDialog = () => {
setVisible(true);
};
return (
<div>
<Button onClick={showDialog}>Start Guide</Button>
<UserGuide
mode="modal"
mask={true}
visible={visible}
steps={[
{
title: 'Welcome to Semi DSM!',
description: <div>You can start from the published theme, or choose {<Typography.Text strong>Create Now</Typography.Text>} to create a new theme</div>,
cover: <Image
width={'600px'}
height={'100%'}
src="https://lf9-static.bytednsdoc.com/obj/eden-cn/nuhpxphk/dsm/dsm_welcome.png"
/>,
position: 'bottom',
},
{
title: 'High-available color palette',
description: 'After selecting the main color, our color algorithm will generate a high-available color palette for you',
cover: <Image
width={'600px'}
height={'100%'}
src="https://lf9-static.bytednsdoc.com/obj/eden-cn/nuhpxphk/dsm/dsm_console.png"
/>,
position: 'bottom',
},
{
title: 'Customize freely',
description: 'Start customizing your design system!',
cover: <Image
width={'600px'}
height={'100%'}
src="https://lf9-static.bytednsdoc.com/obj/eden-cn/nuhpxphk/dsm/dsm_palette.png"
/>,
position: 'bottom',
},
]}
onChange={(current) => {
console.log('Current guide step', current);
}}
onNext={(current) => {
console.log('Next guide step');
}}
onPrev={(current) => {
console.log('Previous guide step');
}}
onFinish={() => {
setVisible(false);
console.log('Guide completed');
}}
onSkip={() => {
setVisible(false);
console.log('Skip guide');
}}
/>
</div>
);
};
```
### No mask
Set by the `mask` property.
```jsx live=true
import React from 'react';
import { UserGuide, Button, Space, Tag, Switch, Image } from '@douyinfe/semi-ui';
() => {
const [visible, setVisible] = useState(false);
const showDialog = () => {
setVisible(true);
};
return (
<div>
<Button id={'mask-demo'} onClick={showDialog}>Start Guide</Button>
<UserGuide
mode="popup"
mask={false}
visible={visible}
steps={[
{
target: document.querySelector('#mask-demo'),
title: 'No Mask',
description: 'Hello ByteDancer!',
},
]}
onFinish={() => {
setVisible(false);
console.log('Guide completed');
}}
onSkip={() => {
setVisible(false);
console.log('Skip guide');
}}
/>
</div>
);
};
```
## API Reference
---
| Properties | Instructions | Type | Default | Version |
| --- | --- | --- | --- | --- |
| className | Custom class name | string | - | |
| current | Current step index | number | 0 | |
| finishText | Text of the last step completion button | string | '完成' | |
| mask | Whether to display the mask | boolean | true | |
| mode | Guide mode, optional values: `popup` (bubble card) or `modal` (modal) | string | popup | |
| nextButtonProps | The properties of the next button | ButtonProps | {} | |
| onChange | Callback when the step changes | function(current: number) | () => void | |
| onFinish | Callback when all steps are completed | function() | () => void | |
| onNext | Callback when the next button is clicked | function(current: number) | () => void | |
| onPrev | Callback when the previous button is clicked | function(current: number) | () => void | |
| onSkip | Callback when the skip button is clicked | function() | () => void | |
| position | The position of the pop-up layer relative to the target element, optional values: `top`, `topLeft`, `topRight`, `left`, `leftTop`, `leftBottom`, `right`, `rightTop`, `rightBottom`, `bottom`, `bottomLeft`, `bottomRight` | string | bottom | |
| prevButtonProps | The properties of the previous button | ButtonProps | {} | |
| showPrevButton | Whether to display the previous button | boolean | true | |
| showSkipButton | Whether to display the skip button | boolean | true | |
| spotlightPadding | The inner padding of the highlight area, in pixels | number | - | |
| steps | Guide step configuration, required | StepItem[] | [] | |
| style | Custom style | React.CSSProperties | - | |
| theme | Theme style, optional values: `default` or `primary` | string | default | |
| visible | Whether to display the guide | boolean | false | |
| getPopupContainer | Specify the parent DOM, the pop-up layer will be rendered to the DOM | () => HTMLElement | - | |
| zIndex | Pop-up layer level | number | 1030 | |
### Steps.Step
| Properties | Instructions | Type | Default | Version |
| --- | --- | --- | --- | --- |
| className | Custom class name | string | - | |
| cover | The cover image of the step | ReactNode | - | |
| target | The target element, the highlight area will focus on this element | (() => Element) \| Element | - | |
| title | Step title | string \| ReactNode | - | |
| description | Step description | ReactNode | - | |
| mask | Whether to display the mask of this step, it will override the global configuration | boolean | - | |
| showArrow | Whether to display the arrow (only valid when mode=`popup`) | boolean | true | |
| spotlightPadding | The inner padding of the highlight area of this step, it will override the global configuration | number | - | |
| theme | The theme of this step, it will override the global configuration | `default` \| `primary` | - | |
| position | The position of the pop-up layer of this step, it will override the global configuration | Position | - | |
## Design Tokens
<DesignToken/>