Show · UserGuide

UserGuide

Used to guide new users through pages

Demos

How to import

<script lang="ts">
    import { UserGuide } from '@fibrae/semi-ui-svelte';
</script>

Basic Usage



Default Tag
Code
<script lang="ts">
    import { Button, Space, Switch, Tag, UserGuide, type UserGuideStepItem } from '@fibrae/semi-ui-svelte';

    let visible = $state(false);
    const steps: UserGuideStepItem[] = [
        {
            target: () => document.querySelector('#basic-demo-1'),
            title: '新手引导',
            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',
        },
    ];
</script>

<div>
    <Button onclick={() => (visible = true)}>开始引导</Button>
    <br />
    <br />
    <Space>
        <Switch aria-label="示例开关" checked id="basic-demo-1" />
        <Tag id="basic-demo-2">Default Tag</Tag>
        <Button id="basic-demo-3">确定</Button>
    </Space>
    <UserGuide bind:visible mask mode="popup" onChange={(current) => console.log('当前引导步骤', current)} onFinish={() => console.log('引导完成')} onNext={() => console.log('下一步引导')} onPrev={() => console.log('上一步引导')} onSkip={() => console.log('跳过引导')} {steps} />
</div>

Theme

popup bubble card mode provides two themes default and primary, set by the theme property.



Default Tag
Code
<script lang="ts">
    import { Button, Space, Switch, Tag, UserGuide, type UserGuideStepItem } from '@fibrae/semi-ui-svelte';

    let visible = $state(false);
    const steps: UserGuideStepItem[] = [
        {
            target: () => document.querySelector('#theme-demo-1'),
            title: '新手引导',
            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',
        },
    ];
</script>

<div>
    <Button onclick={() => (visible = true)}>开始引导</Button>
    <br />
    <br />
    <Space>
        <Switch aria-label="示例开关" checked id="theme-demo-1" />
        <Tag id="theme-demo-2">Default Tag</Tag>
        <Button id="theme-demo-3">确定</Button>
    </Space>
    <UserGuide bind:visible mask mode="popup" onFinish={() => console.log('引导完成')} onSkip={() => console.log('跳过引导')} {steps} theme="primary" />
</div>

popup bubble card mode provides 16 positions, optional values are top, topLeft, topRight, left, leftTop, leftBottom, right, rightTop, rightBottom, bottom, bottomLeft, bottomRight, leftTopOver, rightTopOver, leftBottomOver, rightBottomOver, and can be set by the showArrow property to display the arrow.

Code
<script lang="ts">
    import { Button, UserGuide, type UserGuideStepItem } from '@fibrae/semi-ui-svelte';

    let visible = $state(false);
    const target = () => document.querySelector('#position-demo');
    const steps: UserGuideStepItem[] = [
        { target, title: '新手引导', description: 'Hello ByteDancer!', position: 'top' },
        { target, title: 'New Position', description: 'This is Right Position', position: 'right' },
        { target, title: 'Hide Arrow', description: 'We hide the arrow', position: 'bottom', showArrow: false },
    ];
</script>

<div>
    <Button id="position-demo" onclick={() => (visible = true)}>开始引导</Button>
    <UserGuide bind:visible mask mode="popup" onFinish={() => console.log('引导完成')} onSkip={() => console.log('跳过引导')} {steps} />
</div>

Set the size of the highlight area

Set by the spotlightPadding property.



Default Tag
Code
<script lang="ts">
    import { Button, Space, Switch, Tag, UserGuide, type UserGuideStepItem } from '@fibrae/semi-ui-svelte';

    let visible = $state(false);
    const steps: UserGuideStepItem[] = [
        {
            target: () => document.querySelector('#padding-demo-1'),
            title: '新手引导',
            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',
        },
    ];
</script>

<div>
    <Button onclick={() => (visible = true)}>开始引导</Button>
    <br />
    <br />
    <Space>
        <Switch aria-label="示例开关" checked id="padding-demo-1" />
        <Tag id="padding-demo-2">Default Tag</Tag>
        <Button id="padding-demo-3">确定</Button>
    </Space>
    <UserGuide bind:visible mask mode="popup" onFinish={() => console.log('引导完成')} onSkip={() => console.log('跳过引导')} spotlightPadding={10} {steps} />
</div>

Customize the button

Set by the nextButtonProps and prevButtonProps properties.

Use the nextText and prevText snippets for the button text. The text of the button on the last step is set by finishText.



Default Tag
Code
<script lang="ts">
    import { Button, Space, Switch, Tag, UserGuide, type UserGuideStepItem } from '@fibrae/semi-ui-svelte';

    let visible = $state(false);
    const steps: UserGuideStepItem[] = [
        {
            target: () => document.querySelector('#button-demo-1'),
            title: '新手引导',
            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',
        },
    ];
</script>

<div>
    <Button onclick={() => (visible = true)}>开始引导</Button>
    <br />
    <br />
    <Space>
        <Switch aria-label="示例开关" checked id="button-demo-1" />
        <Tag id="button-demo-2">Default Tag</Tag>
        <Button id="button-demo-3">确定</Button>
    </Space>
    <UserGuide bind:visible finishText="我知道啦!" mask mode="popup" onFinish={() => console.log('引导完成')} onSkip={() => console.log('跳过引导')} prevButtonProps={{ theme: 'borderless' }} {steps}>
        {#snippet nextText()}Next{/snippet}
        {#snippet prevText()}Prev{/snippet}
    </UserGuide>
</div>

Controlled

Set by the current property.

Bind the current step with bind:current and the visibility with bind:visible.



Default Tag
Code
<script lang="ts">
    import { Button, Space, Switch, Tag, UserGuide, type UserGuideStepItem } from '@fibrae/semi-ui-svelte';

    let visible = $state(false);
    let current = $state(0);
    const steps: UserGuideStepItem[] = [
        {
            target: () => document.querySelector('#controlled-demo-1'),
            title: '新手引导',
            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',
        },
    ];

    const finish = (message: string) => {
        current = 0;
        console.log(message);
    };
</script>

<div>
    <Button onclick={() => (visible = true)}>开始引导</Button>
    <br />
    <br />
    <Space>
        <Switch aria-label="示例开关" checked id="controlled-demo-1" />
        <Tag id="controlled-demo-2">Default Tag</Tag>
        <Button id="controlled-demo-3">确定</Button>
    </Space>
    <UserGuide bind:current bind:visible mask mode="popup" onFinish={() => finish('引导完成')} onSkip={() => finish('跳过引导')} {steps} />
</div>

Set by the mode property.

Use the cover snippet in the step data for the cover, and write description as a snippet for rich-text descriptions; a snippet receives { item, index }.

Code
<script lang="ts">
    import { Button, Image, TypographyText, UserGuide, type UserGuideStepItem } from '@fibrae/semi-ui-svelte';

    let visible = $state(false);
    const covers = ['/assets/root-web-sites/sky.jpg', '/assets/root-web-sites/greenleaf.jpg', '/assets/root-web-sites/colorful.jpg'];
</script>

{#snippet welcome()}
    <div>你可以从已发布的主题出发,或者选择<TypographyText strong>立即创造</TypographyText>来创造一个新的主题</div>
{/snippet}

{#snippet cover({ index }: { index: number })}
    <Image height="100%" src={covers[index]} width="600px" />
{/snippet}

<div>
    <Button onclick={() => (visible = true)}>开始引导</Button>
    <UserGuide
        bind:visible
        mask
        mode="modal"
        onChange={(current) => console.log('当前引导步骤', current)}
        onFinish={() => console.log('引导完成')}
        onNext={() => console.log('下一步引导')}
        onPrev={() => console.log('上一步引导')}
        onSkip={() => console.log('跳过引导')}
        steps={[
            { title: '欢迎使用 Semi DSM!', description: welcome, cover, position: 'bottom' },
            { title: '高可用的色盘', description: '选取主色后,我们的颜色算法会为你生成一套高可用的色盘', cover, position: 'bottom' },
            { title: '自由定制', description: '开始定制属于你的设计系统吧!', cover, position: 'bottom' },
        ] satisfies UserGuideStepItem[]}
    />
</div>

No mask

Set by the mask property.

Code
<script lang="ts">
    import { Button, UserGuide, type UserGuideStepItem } from '@fibrae/semi-ui-svelte';

    let visible = $state(false);
    const steps: UserGuideStepItem[] = [
        {
            target: () => document.querySelector('#mask-demo'),
            title: 'No Mask',
            description: 'Hello ByteDancer!',
        },
    ];
</script>

<div>
    <Button id="mask-demo" onclick={() => (visible = true)}>开始引导</Button>
    <UserGuide bind:visible mask={false} mode="popup" onFinish={() => console.log('引导完成')} onSkip={() => console.log('跳过引导')} {steps} />
</div>

API Reference


Props

PropertyDescriptionTypeDefault
classLands on the popover card in popup mode and on the outermost element of the Modal in modal mode.string-
currentIndex of the current step, bound with bind:current. Without it the component keeps the index itself, starting at 0.number-
finishTextText of the finish button on the last step. When empty, the text from the locale pack is used.string-
getPopupContainerIn modal mode the dialog is rendered into this DOM node. In popup mode body scrolling is not locked when it points to an element other than body. The popover card sits in the top layer and is not affected.Type() => HTMLElement-
maskWhether to show the mask. A step's own mask overrides it.booleantrue
modeGuide mode: popup for a bubble card, modal for a dialog.'popup' | 'modal'"popup"
nextButtonPropsProps of the next button. onclick is called before the built-in handling; use the nextText snippet for the button text.UserGuideButtonProps-
nextTextSnippet for the text of the next button; the last step shows finishText. Without it the text from the locale pack is used.Snippet-
onChangeCalled with the new index when the step changes, after current was written.Type(current: number) => void-
onFinishCalled when the finish button on the last step is clicked, after visible was written.Type() => void-
onNextCalled with the new index when the next button is clicked. The last step calls onFinish instead.Type(current: number) => void-
onPrevCalled with the new index when the previous button is clicked.Type(current: number) => void-
onSkipCalled when the skip button is clicked or Escape is pressed, after visible was written.Type() => void-
positionPosition of the bubble card relative to the target element. A step's own position overrides it.Position"bottom"
prevButtonPropsProps of the previous button. onclick is called before the built-in handling; use the prevText snippet for the button text.UserGuideButtonProps-
prevTextSnippet for the text of the previous button. Without it the text from the locale pack is used.Snippet-
showPrevButtonWhether to show the previous button. It is never shown on the first step.booleantrue
showSkipButtonWhether to show the skip button. It is never shown on the last step.booleantrue
spotlightPaddingExtra space in pixels around the highlighted area. A step's own spotlightPadding overrides it; 5 when neither is set.number-
stepsData of the guide steps. A title or description is a string or a snippet, a cover is a snippet; a snippet receives { item, index }.UserGuideStepItem[][]
styleStyle string. Lands on the popover card in popup mode and on .semi-modal in modal mode.string-
themeTheme of the popup mode. A step's own theme overrides it.'default' | 'primary'"default"
visibleWhether the guide is shown, bound with bind:visible. Skip, Escape and finish write false back.boolean-
zIndexThe z-index of the mask in popup mode and of the dialog in modal mode. The popover card sits in the top layer, always above the mask.number1030

UserGuide has no root element. In popup mode class and style land on the popover card; in modal mode class lands on the outermost element of the Modal and style on .semi-modal. Undeclared attributes such as aria-* and native events are dropped. The dialog's accessible name comes only from the title of the current step.

StepItem

Each item of steps (type UserGuideStepItem) holds data only. title and description are strings or snippets and cover is a snippet; a snippet receives { item, index } (type UserGuideStepSnippetProps).

PropertyDescriptionTypeDefault
classCustom class name of the stepstring-
coverCover of the step; without it the step has no cover areaSnippet<[UserGuideStepSnippetProps]>-
targetThe target element, the highlight area will focus on this element. The function form is called when the step is measured and may return null or undefined while the target is absentElement | (() => Element | null | undefined)-
titleTitle of the step, a string or a snippetstring | Snippet<[UserGuideStepSnippetProps]>-
descriptionDescription of the step, a string or a snippetstring | Snippet<[UserGuideStepSnippetProps]>-
maskWhether to display the mask of this step, it will override the global configurationboolean-
showArrowWhether to display the arrow (only valid when mode=popup)booleantrue
spotlightPaddingThe inner padding of the highlight area of this step, it will override the global configurationnumber-
themeThe theme of this step, it will override the global configurationdefault | primary-
positionThe position of the pop-up layer of this step, it will override the global configurationPosition-

Accessibility

  • Each step is a dialog named by the step title; Escape works like clicking Skip.
  • In both modes, focus moves to the primary button (Next or Finish) when each step appears. In popup mode Tab cycles inside the card, and focus returns to the element focused before the guide when it closes; in modal mode, Modal manages the focus cycle and its return.

Design Tokens

These are the component's internal Sass variables and cannot be overridden. To customize styles, override the --semi-* CSS variables (see the Design Token page) or write unlayered CSS rules.
Sass variableValueUsage
$transition_duration-userGuide_spotLight200msspotLight 动画持续时间
$transition_function-userGuide_spotLightcubic-bezier(0.4, 0, 0.2, 1)spotLight 过渡曲线
$color-userGuide_popup-text-defaultvar(--semi-color-text-0)气泡卡片文字颜色 - 默认
$color-userGuide_popup-text-primaryvar(--semi-color-tertiary-light-default)气泡卡片文字颜色 - primary
$color-userGuide_modal_content_indicator-bgvar(--semi-color-primary-light-active)弹窗指示器背景颜色
$color-userGuide_modal_content_indicator-bg-activevar(--semi-color-primary)弹窗指示器背景颜色 - 选中态
$width-userGuide_popover-default400px默认气泡卡片宽度
$height-userGuide_popup_content_cover-default200px默认气泡卡片封面高度
$width-userGuide_modal_content_cover-default600px默认弹窗式卡片封面宽度
$height-userGuide_modal_content_cover-default300px默认弹窗式卡片封面高度
$height-userGuide_modal_content_indicator-default30px默认弹窗式卡片指示器整体高度
$width-userGuide_modal_content_indicator_item-default6px默认弹窗式卡片单个指示器宽度
$height-userGuide_modal_content_indicator_item-default6px默认弹窗式卡片单个指示器高度
$font-userGuide_popup_content_title-lineHeight24px气泡卡片标题行高
$font-userGuide_popup_content_description-lineHeight20px气泡卡片详情行高
$font-userGuide_popup_content_indicator-lineHeight20px气泡卡片指示器行高
$font-userGuide_modal_content_title-lineHeight24px弹窗式卡片标题行高
$font-userGuide_modal_content_description-lineHeight20px弹窗式卡片详情行高
$spacing-userGuide_popup_content_body-padding24px气泡卡片内边距
$spacing-userGuide_popup_content_title-marginBottom8px气泡卡片标题底部外边距
$spacing-userGuide_popup_content_description-marginBottom48px气泡卡片详情底部外边距
$spacing-userGuide_popup_content_button-gap12px气泡卡片底部按钮间距
$spacing-userGuide_popup_content_button-marginLeft120px气泡卡片按钮组左边距
$spacing-userGuide_modal_content_title-marginBottom8px弹窗式卡片标题底部外边距
$spacing-userGuide_modal_content_body-padding24px 48px弹窗式卡片body内边距
$spacing-userGuide_modal_content_footer-padding24px弹窗式卡片footer内边距
$spacing-userGuide_popup_content_indicator-gap8px弹窗式片指示器间距
$spacing-userGuide_modal_content_button-gap12px弹窗式卡片底部按钮间距
$radius-userGuide_popup_content_covervar(--semi-border-radius-medium) var(--semi-border-radius-medium) 0 0气泡卡片封面圆角
$radius-userGuide_modal_content_indicatorvar(--semi-border-radius-large)气泡卡片指示器圆角
$font-userGuide_popup_content_title-fontSize$font-size-header-5气泡卡片标题字体大小
$font-userGuide_popup_content_description-fontSize$font-size-regular气泡卡片详情字体大小
$font-userGuide_popup_content_title-fontWeight$font-weight-bold气泡卡片标题字重
$font-userGuide_modal_content_title-fontSize$font-size-header-5弹窗式卡片标题字体大小
$font-userGuide_modal_content_description-fontSize$font-size-regular弹窗式卡详情字体大小
$font-userGuide_modal_content_title-fontWeight$font-weight-bold弹窗式卡片标题字重