Popover - Svelte - Semi Design Next

When to Use

When the target element has further description and related operations, it can be included in the card and displayed according to the user's operational behavior.

The difference with Tooltip is that users can operate on elements on the floating layer, so it can carry more complex content, such as links or buttons.

Demos

How to import

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

Cautions

Popover applies the trigger attributes and event listeners to the trigger element, and uses the real DOM element of the trigger to calculate the position of the popup layer, so the trigger supports the following forms:

The child snippet: spread its argument { props } whole onto the element that receives focus, either a real DOM element such as span, div, p..., or a component that passes its props through to its root DOM element (such as <Button {...props} />)
The children snippet (content written inside the tag): text, a component or several nodes, which Popover wraps in a span as the trigger element

Component

Text DOM

Code

<script lang="ts">
    import { IllustrationSuccess, IllustrationSuccessDark } from '@fibrae/semi-illustrations-svelte';
    import { Empty, Popover, Space, Tag } from '@fibrae/semi-ui-svelte';

    const style = 'border: 2px solid var(--semi-color-border); padding-left: 4px; padding-right: 4px; border-radius: 4px';
    const imageStyle = 'width: 150px; height: 150px';
</script>

{#snippet card()}
    <Empty style="width: 400px; margin: 0 auto; display: flex; padding: 20px" title="先进的设计 / 研发协作方式">
        {#snippet image()}
            <IllustrationSuccess style={imageStyle} />
        {/snippet}
        {#snippet darkModeImage()}
            <IllustrationSuccessDark style={imageStyle} />
        {/snippet}
        {#snippet description()}使用 Semi D2C 快速还原 Figma 设计稿，一键转代码{/snippet}
    </Empty>
{/snippet}

<Space>
    <Popover content={card}>
        <Tag {style}>Component</Tag>
    </Popover>
    <Popover content={card}>Text</Popover>
    <Popover content={card}>
        {#snippet child({ props })}
            <span {...props} {style}>DOM</span>
        {/snippet}
    </Popover>
</Space>

Basic Usage

Write the trigger inside the Popover tag (the trigger is a Tag in the example below) and pass the popup content through the content snippet.
The cautions are the same as Tooltip

悬停此处

Code

<script lang="ts">
    import { IllustrationSuccess, IllustrationSuccessDark } from '@fibrae/semi-illustrations-svelte';
    import { Empty, Popover, Tag } from '@fibrae/semi-ui-svelte';

    const imageStyle = 'width: 150px; height: 150px';
</script>

{#snippet card()}
    <Empty style="width: 400px; margin: 0 auto; display: flex; padding: 20px" title="先进的设计 / 研发协作方式">
        {#snippet image()}
            <IllustrationSuccess style={imageStyle} />
        {/snippet}
        {#snippet darkModeImage()}
            <IllustrationSuccessDark style={imageStyle} />
        {/snippet}
        {#snippet description()}使用 Semi D2C 快速还原 Figma 设计稿，一键转代码{/snippet}
    </Empty>
{/snippet}

<Popover content={card}>
    <Tag>悬停此处</Tag>
</Popover>

Pop-up Position

Support twelve directions.

Top

Left

Right

Bottom

Code

<script lang="ts">
    import { IllustrationSuccess, IllustrationSuccessDark } from '@fibrae/semi-illustrations-svelte';
    import { Empty, Popover, Tag, type Position } from '@fibrae/semi-ui-svelte';

    const tops: [Position, string][] = [
        ['topLeft', 'TL'],
        ['top', 'Top'],
        ['topRight', 'TR'],
    ];
    const lefts: [Position, string][] = [
        ['leftTop', 'LT'],
        ['left', 'Left'],
        ['leftBottom', 'LB'],
    ];
    const rights: [Position, string][] = [
        ['rightTop', 'RT'],
        ['right', 'Right'],
        ['rightBottom', 'RB'],
    ];
    const bottoms: [Position, string][] = [
        ['bottomLeft', 'BL'],
        ['bottom', 'Bottom'],
        ['bottomRight', 'BR'],
    ];
    const imageStyle = 'width: 150px; height: 150px';
</script>

{#snippet content()}
    <Empty style="width: 400px; margin: 0 auto; display: flex; padding: 20px" title="先进的设计 / 研发协作方式">
        {#snippet image()}
            <IllustrationSuccess style={imageStyle} />
        {/snippet}
        {#snippet darkModeImage()}
            <IllustrationSuccessDark style={imageStyle} />
        {/snippet}
        {#snippet description()}使用 Semi D2C 快速还原 Figma 设计稿，一键转代码{/snippet}
    </Empty>
{/snippet}

<div>
    <div style="margin-left: 80px; white-space: nowrap">
        {#each tops as [position, label] (position)}
            <Popover {content} {position}>
                <Tag style="margin: 8px; padding: 20px">{label}</Tag>
            </Popover>
        {/each}
    </div>
    <div style="width: 80px; float: left">
        {#each lefts as [position, label] (position)}
            <Popover {content} {position}>
                <Tag style="margin: 8px; padding: 20px; width: 60px">{label}</Tag>
            </Popover>
        {/each}
    </div>
    <div style="width: 40px; margin-left: 300px">
        {#each rights as [position, label] (position)}
            <Popover {content} {position}>
                <Tag style="margin: 8px; padding: 20px; width: 60px">{label}</Tag>
            </Popover>
        {/each}
    </div>
    <div style="margin-left: 80px; clear: both; white-space: nowrap">
        {#each bottoms as [position, label] (position)}
            <Popover {content} {position}>
                <Tag style="margin: 8px; padding: 20px; width: 60px">{label}</Tag>
            </Popover>
        {/each}
    </div>
</div>

Controlled Display

Set trigger="custom". In this scenario, Popover's display is completely at the control of parameter visible, which can be used with bind:visible.

受控显示

受控隐藏

Code

<script lang="ts">
    import { IllustrationSuccess, IllustrationSuccessDark } from '@fibrae/semi-illustrations-svelte';
    import { Empty, Popover, Radio, RadioGroup, type RadioValue } from '@fibrae/semi-ui-svelte';

    let value = $state<RadioValue | undefined>(0);
    const imageStyle = 'width: 150px; height: 150px';
</script>

{#snippet content()}
    <Empty style="width: 400px; margin: 0 auto; display: flex; padding: 20px" title="先进的设计 / 研发协作方式">
        {#snippet image()}
            <IllustrationSuccess style={imageStyle} />
        {/snippet}
        {#snippet darkModeImage()}
            <IllustrationSuccessDark style={imageStyle} />
        {/snippet}
        {#snippet description()}使用 Semi D2C 快速还原 Figma 设计稿，一键转代码{/snippet}
    </Empty>
{/snippet}

<Popover {content} trigger="custom" visible={value === 1}>
    <span style="display: inline-block">
        <RadioGroup bind:value type="button">
            <Radio value={1}>受控显示</Radio>
            <Radio value={0}>受控隐藏</Radio>
        </RadioGroup>
    </span>
</Popover>

Conditional trigger (condition)

When condition={false}, Popover will not respond to hover/click/focus triggers (with trigger="custom", visible still decides); when condition changes from true to false, an open popup closes at once; with visible controlled it only calls onVisibleChange(false), and the popup closes once the owner sets visible to false.

Code

<script lang="ts">
    import { Button, Popover, Space, Switch, TypographyText } from '@fibrae/semi-ui-svelte';

    let enabled = $state(true);
    const text = $derived(`condition is ${enabled ? 'true' : 'false'}`);
</script>

{#snippet content()}{text}{/snippet}

<Space align="center">
    <TypographyText id="popover-condition-label">condition</TypographyText>
    <Switch aria-labelledby="popover-condition-label" bind:checked={enabled} />
    <Popover condition={enabled} {content}>
        {#snippet child({ props })}
            <Button {...props}>Hover me</Button>
        {/snippet}
    </Popover>
    <Popover condition={enabled} {content} trigger="click">
        {#snippet child({ props })}
            <Button {...props}>Click me</Button>
        {/snippet}
    </Popover>
</Space>

Show Small Triangle

Popover also supports the display of a small triangle.

The floating layer in this mode has a default style that you can overwrite by passing the style parameters.

Top

Left

Right

Bottom

Code

<script lang="ts">
    import { Popover, Tag, type Position } from '@fibrae/semi-ui-svelte';

    const tops: [Position, string][] = [
        ['topLeft', 'TL'],
        ['top', 'Top'],
        ['topRight', 'TR'],
    ];
    const lefts: [Position, string][] = [
        ['leftTop', 'LT'],
        ['left', 'Left'],
        ['leftBottom', 'LB'],
    ];
    const rights: [Position, string][] = [
        ['rightTop', 'RT'],
        ['right', 'Right'],
        ['rightBottom', 'RB'],
    ];
    const bottoms: [Position, string][] = [
        ['bottomLeft', 'BL'],
        ['bottom', 'Bottom'],
        ['bottomRight', 'BR'],
    ];
</script>

{#snippet content()}
    <article>
        Hi ByteDancer, this is a popover.
        <br />
        We have 2 lines.
    </article>
{/snippet}

<div class="tag-margin-right" style="padding-left: 40px">
    <div style="margin-left: 40px; white-space: nowrap">
        {#each tops as [position, label] (position)}
            <Popover {content} {position} showArrow>
                <Tag>{label}</Tag>
            </Popover>
        {/each}
    </div>
    <div style="width: 40px; float: left">
        {#each lefts as [position, label] (position)}
            <Popover {content} {position} showArrow>
                <Tag>{label}</Tag>
            </Popover>
        {/each}
    </div>
    <div style="width: 40px; margin-left: 180px">
        {#each rights as [position, label] (position)}
            <Popover {content} {position} showArrow>
                <Tag>{label}</Tag>
            </Popover>
        {/each}
    </div>
    <div style="margin-left: 40px; clear: both; white-space: nowrap">
        {#each bottoms as [position, label] (position)}
            <Popover {content} {position} showArrow>
                <Tag>{label}</Tag>
            </Popover>
        {/each}
    </div>
</div>

Arrow Point at Center

Under the condition of showArrow=true, you can pass in arrowPointAtCenter=true so that the small triangle always points to the center of the element.

Top

Left

Right

Bottom

Code

<script lang="ts">
    import { Popover, Tag, type Position } from '@fibrae/semi-ui-svelte';

    const tops: [Position, string][] = [
        ['topLeft', 'TL'],
        ['top', 'Top'],
        ['topRight', 'TR'],
    ];
    const lefts: [Position, string][] = [
        ['leftTop', 'LT'],
        ['left', 'Left'],
        ['leftBottom', 'LB'],
    ];
    const rights: [Position, string][] = [
        ['rightTop', 'RT'],
        ['right', 'Right'],
        ['rightBottom', 'RB'],
    ];
    const bottoms: [Position, string][] = [
        ['bottomLeft', 'BL'],
        ['bottom', 'Bottom'],
        ['bottomRight', 'BR'],
    ];
</script>

{#snippet content()}
    <article>
        Hi ByteDancer, this is a popover.
        <br />
        We have 2 lines.
    </article>
{/snippet}

<div class="tag-margin-right" style="padding-left: 40px">
    <div style="margin-left: 40px; white-space: nowrap">
        {#each tops as [position, label] (position)}
            <Popover arrowPointAtCenter {content} {position} showArrow>
                <Tag>{label}</Tag>
            </Popover>
        {/each}
    </div>
    <div style="width: 40px; float: left">
        {#each lefts as [position, label] (position)}
            <Popover arrowPointAtCenter {content} {position} showArrow>
                <Tag>{label}</Tag>
            </Popover>
        {/each}
    </div>
    <div style="width: 40px; margin-left: 180px">
        {#each rights as [position, label] (position)}
            <Popover arrowPointAtCenter {content} {position} showArrow>
                <Tag>{label}</Tag>
            </Popover>
        {/each}
    </div>
    <div style="margin-left: 40px; clear: both; white-space: nowrap">
        {#each bottoms as [position, label] (position)}
            <Popover arrowPointAtCenter {content} {position} showArrow>
                <Tag>{label}</Tag>
            </Popover>
        {/each}
    </div>
</div>

Set Floating Layer Background Color

If you need to customize the background color or border color of the floating layer, please Be sure to set backgroundColor and borderColor properties in style separately. This enables the "small triangle" to apply the same background color and border color.

Colorful Popover

Code

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

<div>
    <Popover aria-label="Colorful Popover" position="right" showArrow style="background-color: var(--semi-blue-6); border-color: var(--semi-blue-6); color: var(--semi-color-white); border-width: 1px; border-style: solid" trigger="custom" visible>
        <Tag style="background-color: var(--semi-blue-6); color: var(--semi-color-white)">Colorful Popover</Tag>
        {#snippet content()}
            <article style="padding: 4px">Hi, Semi UI Popover.</article>
        {/snippet}
    </Popover>
</div>

The content snippet receives { initialFocusRef } as its argument. Bind it to a focusable element with {@attach initialFocusRef}, and it will automatically focus at this position when the panel is opened. On a component, {@attach} lands on the inner native control that receives aria-* and tabindex (such as the native <input> of Input in the example).

Code

<script lang="ts">
    import { Button, Input, Popover, Space } from '@fibrae/semi-ui-svelte';
</script>

<Popover trigger="click">
    <Button>click me</Button>
    {#snippet content({ initialFocusRef })}
        <div style="padding: 12px">
            <Space>
                <Button>first focusable element</Button>
                <Input {@attach initialFocusRef} placeholder="focus here" />
            </Space>
        </div>
    {/snippet}
</Popover>

Please refer to Use with Tooltip/Popconfirm

API Reference

Props

Property	Description	Type	Default
afterClose	Called after the popup has closed and its leave animation has finished.	`TooltipProps['afterClose']`	-
afterOpen	Called after the popup has opened and its enter animation has finished, or right after opening when there is no enter animation, controlled or not; not called for an open that is closed before the enter animation ends.	`TooltipProps['afterOpen']`	-
aria-describedby	aria-describedby of the popup when its role is dialog.	`string`	-
aria-label	aria-label of the popup when its role is dialog.	`string`	-
aria-labelledby	aria-labelledby of the popup when its role is dialog.	`string`	-
arrowPointAtCenter	Whether the arrow points at the center of the trigger. Requires showArrow.	`boolean`	-
arrowStyle	borderColor, backgroundColor and borderOpacity of the arrow. They follow backgroundColor and borderColor of the card style by default.	`ArrowStyle`	-
autoAdjustOverflow	Whether the popup flips automatically when it would be clipped.	`boolean`	`true`
child	Snippet that renders the trigger element itself. Its argument `{ props }` must be spread whole onto the trigger; when `child` is passed, `children` has no effect.	`TooltipProps['child']`	-
children	Snippet for the trigger. It is wrapped in Tooltip's own span, which receives the trigger attributes.	`TooltipProps['children']`	-
class	Class name of the popup.	`string`	-
clickToHide	Whether a click on the popup or anything inside it closes the popup.	`boolean`	-
closeOnEsc	Whether Esc closes the open popup. With trigger custom it only calls onEscKeyDown and the caller decides whether to close.	`boolean`	`true`
condition	Whether the popup may be triggered. Only an explicit false disables the hover, click and focus triggers; with trigger custom, visible still shows the popup. Changing it from true to false closes an open popup at once; with a controlled visible it only calls onVisibleChange(false), and the popup closes once the caller writes back.	`boolean`	-
content	Snippet for the card content. Its argument `{ initialFocusRef }` is a callback; write `{@attach initialFocusRef}` to bind it to the element that receives focus when the popup opens.	`TooltipProps['content']`	-
contentClassName	Class name of the content card in the popup.	`ClassValue`	-
disableArrowKeyDown	Whether the arrow keys on the trigger are prevented from moving focus into the popup.	`boolean`	-
disableFocusListener	Whether keyboard focus is ignored when trigger is hover.	`boolean`	-
guardFocus	Whether Tab cycles inside the popup while focus is in it.	`boolean`	`true`
keepDOM	Whether the popup content stays mounted while closed.	`boolean`	-
motion	Whether the popup is animated.	`boolean`	`true`
mouseEnterDelay	Milliseconds before the popup shows after the pointer enters. Applies to the hover and focus triggers.	`number`	-
mouseLeaveDelay	Milliseconds before the popup hides after the pointer leaves. Applies to the hover and focus triggers; not less than mouseEnterDelay.	`number`	-
onClickOutSide	Called when the mouse is pressed outside of the trigger and the open popup. Only for trigger click, contextMenu or custom.	`TooltipProps['onClickOutSide']`	-
onEscKeyDown	Called when Esc is pressed while the popup is open and closeOnEsc is true.	`TooltipProps['onEscKeyDown']`	-
onOpen	Called once per opening when the popup is shown, as its enter animation starts, before afterOpen, controlled or not; not called for a hover open withdrawn because the pointer already left.	`TooltipProps['onOpen']`	-
onVisibleChange	Called when the visibility of the popup changes; with a controlled visible it reports only requests from user interaction, not changes the caller makes to visible.	`TooltipProps['onVisibleChange']`	-
position	Position of the popup relative to the trigger element, in twelve directions.	`TooltipProps['position']`	`"bottom"`
prefixCls	Class prefix of the popup. A custom value drops the Popover styles.	`string`	`"semi-popover"`
returnFocusOnClose	Whether focus returns to the trigger after Esc closes the popup.	`boolean`	`true`
role	ARIA role of the popup. Omitted, it is dialog for the click, contextMenu and custom triggers and tooltip for the rest; pass presentation when the popup only belongs to another control, such as a combobox list.	`string`	-
showArrow	Whether the arrow is shown.	`boolean`	`false`
spacing	Distance in pixels between the popup and the trigger. An object sets the horizontal and vertical distances. Omitted, it is 4 without an arrow and 10 with one.	`number \| { x: number; y: number }`	-
stopPropagation	Whether click, mousedown and focus in/out events on the popup stop propagating.	`boolean \| string`	-
style	Style string of the popup; its background-color and border-color also color the arrow.	`string`	-
trigger	When the popup shows. With custom, visible alone decides.	`TooltipProps['trigger']`	`"hover"`
visible	Whether the popup is shown, used with trigger custom; bind it with `bind:visible`. When given, this value decides.	`boolean`	-

Methods

Method	Description	Type
focusTrigger	Focuses the trigger element. Only works when returnFocusOnClose is true and trigger is not custom.	`Type`
rePosition	Recomputes the popup position from the trigger's current position at once. The popup already follows scrolling, window resizing, trigger moves and size changes of the trigger or popup, so this is rarely needed; following a trigger move lands a frame late, so call this to align within the same frame.	`Type`

class and style land on the popup layer, and other undeclared attributes are dropped (Popover has no root DOM element); the trigger attributes are only added to the trigger element. bind:this receives the instance methods, not a DOM element.

Accessibility

ARIA

About role
- If the trigger is set to click, contextMenu or custom, the PopoverContent element has role set to dialog.
- If the trigger is set to hover or focus, it has role set to tooltip.
- The role prop overrides the default. A dialog needs a name: pass aria-label, or point aria-labelledby at a heading in the content; an unnamed dialog logs a warning in development
Popover's content
- The content wrapper will be automatically added with the id attribute
Popover's children (for a tooltip they only get aria-describedby; for other roles, such as presentation, nothing is added)
- Will be automatically added aria-expanded attribute, when Popover is visible, the attribute value is true, when invisible Is false
- Will be automatically added aria-haspopup attribute, which is dialog
- Will be automatically added aria-controls attribute, which is the id of the content wrapper

Keyboard and Focus

When the Popover trigger method is set to hover: Open the Popover when the mouse is hovered or focused
When the Popover trigger method is set to click: Click the trigger or focus and use the Enter key to open the Popover
After the Popover is activated, press the arrow key ⬇️ to move the focus to the Popover. At this time, the focus is on the first interactive element in the Popover by default, and the user can also customize the focus position (if there is no interactive element in the Popover, it will appear as No response)
Use the Tab key when the focus is in the Popover, the focus will cycle in the Popover, and use Shift + Tab to move the focus in the opposite direction
Keyboard users can close the Popover by pressing Esc, after closing the focus returns to the trigger (when the trigger is click)

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 variable	Value	Usage
$animation_duration-popover-out	100ms	popover-显示及收起动画-动画持续时间
$animation_function-popover-out	cubic-bezier(0.215, 0.61, 0.355, 1)	popover-显示及收起动画-动画插值函数
$horizontal-rate-popover	0.24	水平方向矫正因子
$color-popover_arrow-icon-default	unset	箭头图标
$color-popover-bg-default	var(--semi-color-bg-3)	默认背景色
$color-popover-border-default	var(--semi-color-border)	默认描边颜色
$color-popover-arrow-border	var(--semi-color-border)	箭头描边颜色
$color-popover-arrow-bg	var(--semi-color-bg-3)	箭头默认背景色
$width-popover_arrow	24px	水平箭头宽度
$height-popover_arrow	8px	水平箭头高度
$height-popover_arrow_vertical	24px	垂直箭头高度
$width-popover_arrow_vertical	8px	垂直箭头宽度
$width-popover_title-border	1px
$spacing-popover_title-padding	8px	气泡卡片标题内边距
$spacing-popover_withArrow-padding	12px	带箭头的气泡卡片标题内边距
$spacing-popover_arrow_adjusted_offset-y	6px	垂直方向上的校正偏移量，主要修正三角形有棱角的问题
$spacing-popover_arrow_adjusted_offset-x	math.round($horizontal-rate-popover * $width-popover_arrow)	水平方向上的校正偏移量，主要修正三角形有棱角的问题
$radius-popover	var(--semi-border-radius-medium)	气泡卡片的圆角大小
$filter-popover-bg	none

FAQ

Why the position of the popover overlay card and the relative position of the overlay trigger are not as expected?
Popover relies on Tooltip at the bottom. In order to calculate positioning, Tooltip needs to obtain the real DOM elements of children. Therefore, the Popover type currently supports the following types of children:
1. The child snippet: spread props onto a real DOM element, or onto a component that passes its props through to its root DOM element
2. The children snippet (text, a component, several nodes), which Popover wraps in a span
When Semi Input with prefix is used as the trigger, even if the same width of Input and Popover content are set, the position of the floating card is still positioned relative to the input box that does not contain the prefix part. At this time, just put another div on the outer layer of the trigger to solve the problem.
Why does the popover layer card lose its width and wrap unexpectedly when the width is not enough near the screen border?

After Chromium 104, the wrapping rendering strategy when the width of the screen border text is not enough has changed. For details, see issue #1022, the semi-side has been This problem was fixed in v2.17.0.

When to Use

Demos

How to import

Cautions

Basic Usage

Pop-up Position

Controlled Display

Conditional trigger (condition)

Show Small Triangle

Arrow Point at Center

Set Floating Layer Background Color

Initialize the Focus Position of Popup Layer

Use with Tooltip or Popconfirm

API Reference

Accessibility

ARIA

Keyboard and Focus

Design Tokens

FAQ