index-en-US.md 19 KB
localeCode: en-US order: 82 category: Show title: UserGuide icon: doc-userGuide brief: Used to guide new users through pages
showNew: true
Demos
How to import
import { UserGuide } from '@douyinfe/semi-ui';
Basic Usage
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.
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.
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.
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.
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.
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.
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.
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 | - |