Preview Card

A link that shows a destination preview without interrupting keyboard or screen reader navigation.

The principles of good typography remain in the digital age.

<script lang="ts">
	import { PreviewCard } from '@sveltery/base/preview-card';
</script>

<PreviewCard.Root>
	<p class="text-base text-neutral-950 text-balance dark:text-white">
		The principles of good
		<PreviewCard.Trigger
			class="text-neutral-950 underline decoration-neutral-950/60 decoration-1 underline-offset-2 outline-0 hover:decoration-neutral-950 data-popup-open:decoration-neutral-950 focus-visible:no-underline focus-visible:outline-2 focus-visible:outline-neutral-950 dark:text-white dark:decoration-white/60 dark:hover:decoration-white dark:data-popup-open:decoration-white dark:focus-visible:outline-white"
			href="https://en.wikipedia.org/wiki/Typography"
		>
			typography
		</PreviewCard.Trigger>
		remain in the digital age.
	</p>

	<PreviewCard.Portal>
		<PreviewCard.Positioner sideOffset={8}>
			<PreviewCard.Popup
				class="relative h-[var(--popup-height,auto)] w-[var(--popup-width,auto)] origin-[var(--transform-origin)] border border-neutral-950 bg-white text-neutral-950 shadow-[0.25rem_0.25rem_0] shadow-black/12 transition-[transform,opacity] duration-100 ease-out data-ending-style:[transform:scale(0.98)] data-ending-style:opacity-0 data-starting-style:[transform:scale(0.98)] data-starting-style:opacity-0 dark:border-white dark:bg-neutral-950 dark:text-white dark:shadow-none"
			>
				<PreviewCard.Arrow
					class="relative block h-1.5 w-3 overflow-clip data-[side=bottom]:top-[-6px] data-[side=left]:right-[-9px] data-[side=left]:rotate-90 data-[side=right]:left-[-9px] data-[side=right]:-rotate-90 data-[side=top]:bottom-[-6px] data-[side=top]:rotate-180 before:absolute before:bottom-0 before:left-1/2 before:h-[calc(6px*sqrt(2))] before:w-[calc(6px*sqrt(2))] before:border before:border-neutral-950 before:bg-white before:content-[''] before:[transform:translate(-50%,50%)_rotate(45deg)] dark:before:border-white dark:before:bg-neutral-950"
				/>
				<div class="flex w-min flex-col gap-2 p-2">
					<img
						width="224"
						height="150"
						class="block max-w-none"
						src="https://images.unsplash.com/photo-1619615391095-dfa29e1672ef?q=80&w=448&h=300"
						alt="Station Hofplein signage in Rotterdam, Netherlands"
					/>
					<p class="text-sm">
						<strong>Typography</strong> is the art and science of arranging type to make written language
						clear, visually appealing, and effective in communication.
					</p>
				</div>
			</PreviewCard.Popup>
		</PreviewCard.Positioner>
	</PreviewCard.Portal>
</PreviewCard.Root>

Usage guidelines

Protect screen reader users' current context: Exposing each preview to screen readers would force users through its contents before they could continue through the page, repeatedly disrupting their current context. Keep the link as the only accessible interface and include all previewed information at its destination.
Keep popup content supplementary: Avoid placing unique or essential information in the popup unless it is also available on the linked page. For the reason above, preview card content is not touch, keyboard or screen reader navigable. It acts as a visual progressive enhancement for sighted mouse and keyboard users only.

Anatomy

Import the component and assemble its parts:

Anatomy

<script lang="ts">
	import { PreviewCard } from '@sveltery/base/preview-card';
</script>

<PreviewCard.Root>
	<PreviewCard.Trigger />
	<PreviewCard.Portal>
		<PreviewCard.Backdrop />
		<PreviewCard.Positioner>
			<PreviewCard.Popup>
				<PreviewCard.Arrow />
				<PreviewCard.Viewport />
			</PreviewCard.Popup>
		</PreviewCard.Positioner>
	</PreviewCard.Portal>
</PreviewCard.Root>

A preview card can be controlled by a trigger located either inside or outside the <PreviewCard.Root> component. For simple, one-off interactions, place the <PreviewCard.Trigger> inside <PreviewCard.Root>, as shown in the example at the top of this page.

However, if defining the preview card's content next to its trigger is not practical, you can use a detached trigger. This involves placing the <PreviewCard.Trigger> outside of <PreviewCard.Root> and linking them with a handle created by the PreviewCard.createHandle() function.

The imperative methods on the handle, such as open() and close(), require a <PreviewCard.Root> using the same handle to be mounted. Calls made while no root is attached to the handle — before one mounts, or after it unmounts — are ignored. Each time a root mounts, it starts from fresh state: a call made while no root was attached is not replayed, and no open state carries over from a previous mount.

Detached triggers

<script lang="ts">
	import { PreviewCard } from '@sveltery/base/preview-card';

	const demoPreviewCard = PreviewCard.createHandle();
</script>

<PreviewCard.Trigger handle={demoPreviewCard} href="#">Link</PreviewCard.Trigger>

<PreviewCard.Root handle={demoPreviewCard}>...</PreviewCard.Root>

The principles of good typography remain in the digital age.

<script lang="ts">
	import { PreviewCard } from '@sveltery/base/preview-card';

	const demoPreviewCard = PreviewCard.createHandle();
</script>

<div>
	<p class="text-base text-neutral-950 text-balance dark:text-white">
		The principles of good
		<PreviewCard.Trigger
			class="text-neutral-950 underline decoration-neutral-950/60 decoration-1 underline-offset-2 outline-0 hover:decoration-neutral-950 data-popup-open:decoration-neutral-950 focus-visible:no-underline focus-visible:outline-2 focus-visible:outline-neutral-950 dark:text-white dark:decoration-white/60 dark:hover:decoration-white dark:data-popup-open:decoration-white dark:focus-visible:outline-white"
			handle={demoPreviewCard}
			href="https://en.wikipedia.org/wiki/Typography"
		>
			typography
		</PreviewCard.Trigger>
		remain in the digital age.
	</p>

	<PreviewCard.Root handle={demoPreviewCard}>
		<PreviewCard.Portal>
			<PreviewCard.Positioner sideOffset={8}>
				<PreviewCard.Popup
					class="relative h-[var(--popup-height,auto)] w-[var(--popup-width,auto)] origin-[var(--transform-origin)] border border-neutral-950 bg-white text-neutral-950 shadow-[0.25rem_0.25rem_0] shadow-black/12 transition-[transform,opacity] duration-100 ease-out data-ending-style:[transform:scale(0.98)] data-ending-style:opacity-0 data-starting-style:[transform:scale(0.98)] data-starting-style:opacity-0 dark:border-white dark:bg-neutral-950 dark:text-white dark:shadow-none"
				>
					<PreviewCard.Arrow
						class="relative block h-1.5 w-3 overflow-clip data-[side=bottom]:top-[-6px] data-[side=left]:right-[-9px] data-[side=left]:rotate-90 data-[side=right]:left-[-9px] data-[side=right]:-rotate-90 data-[side=top]:bottom-[-6px] data-[side=top]:rotate-180 before:absolute before:bottom-0 before:left-1/2 before:h-[calc(6px*sqrt(2))] before:w-[calc(6px*sqrt(2))] before:border before:border-neutral-950 before:bg-white before:content-[''] before:[transform:translate(-50%,50%)_rotate(45deg)] dark:before:border-white dark:before:bg-neutral-950"
					/>
					<div class="flex w-min flex-col gap-2 p-2">
						<img
							width="224"
							height="150"
							class="block max-w-none"
							src="https://images.unsplash.com/photo-1619615391095-dfa29e1672ef?q=80&w=448&h=300"
							alt="Station Hofplein signage in Rotterdam, Netherlands"
						/>
						<p class="text-sm">
							<strong>Typography</strong> is the art and science of arranging type to make written language
							clear, visually appealing, and effective in communication.
						</p>
					</div>
				</PreviewCard.Popup>
			</PreviewCard.Positioner>
		</PreviewCard.Portal>
	</PreviewCard.Root>
</div>

Multiple triggers

A single preview card can be opened by multiple trigger elements. You can achieve this by using the same handle for several detached triggers, or by placing multiple <PreviewCard.Trigger> components inside a single <PreviewCard.Root>.

Multiple triggers within the Root part

<PreviewCard.Root>
	<PreviewCard.Trigger href="#">Trigger 1</PreviewCard.Trigger>
	<PreviewCard.Trigger href="#">Trigger 2</PreviewCard.Trigger>
	...
</PreviewCard.Root>

Multiple detached triggers

<script lang="ts">
	import { PreviewCard } from '@sveltery/base/preview-card';

	const demoPreviewCard = PreviewCard.createHandle();
</script>

<PreviewCard.Trigger handle={demoPreviewCard} href="#">Trigger 1</PreviewCard.Trigger>

<PreviewCard.Trigger handle={demoPreviewCard} href="#">Trigger 2</PreviewCard.Trigger>

<PreviewCard.Root handle={demoPreviewCard}>...</PreviewCard.Root>

The preview card can render different content depending on which trigger opened it. This is achieved by passing a payload to the <PreviewCard.Trigger> and using the children snippet of <PreviewCard.Root>, which receives the payload.

The payload can be strongly typed by providing a type argument to the createHandle() function:

Detached triggers with payload

<script lang="ts">
	import { PreviewCard } from '@sveltery/base/preview-card';

	const demoPreviewCard = PreviewCard.createHandle<{ title: string }>();
</script>

<PreviewCard.Trigger handle={demoPreviewCard} payload={{ title: 'Trigger 1' }} href="#">
	Trigger 1
</PreviewCard.Trigger>

<PreviewCard.Trigger handle={demoPreviewCard} payload={{ title: 'Trigger 2' }} href="#">
	Trigger 2
</PreviewCard.Trigger>

<PreviewCard.Root handle={demoPreviewCard}>
	{#snippet children({ payload })}
		<PreviewCard.Portal>
			<PreviewCard.Positioner sideOffset={8}>
				<PreviewCard.Popup>
					{#if payload !== undefined}
						<span>Preview card opened by {payload.title}</span>
					{/if}
				</PreviewCard.Popup>
			</PreviewCard.Positioner>
		</PreviewCard.Portal>
	{/snippet}
</PreviewCard.Root>

Controlled mode with multiple triggers

You can control the preview card's open state externally by binding the open prop on <PreviewCard.Root>. This allows you to manage the preview card's visibility based on your application's state. When using multiple triggers, you have to manage which trigger is active by binding the triggerId prop on <PreviewCard.Root> and setting the id prop on each <PreviewCard.Trigger>.

Note that there is no separate onTriggerIdChange prop. bind:triggerId follows the trigger that opens or closes the preview card. The onOpenChange callback also receives an additional argument, eventDetails, which contains the trigger element that initiated the state change.

Discover typography, design, or art.

<script lang="ts">
	import type { Snippet } from 'svelte';
	import { PreviewCard } from '@sveltery/base/preview-card';

	const demoPreviewCard = PreviewCard.createHandle<Snippet>();

	let open = $state(false);
	let triggerId = $state<string | null>(null);

	const linkClass =
		'text-neutral-950 underline decoration-neutral-950/60 decoration-1 underline-offset-2 outline-0 hover:decoration-neutral-950 data-popup-open:decoration-neutral-950 focus-visible:no-underline focus-visible:outline-2 focus-visible:outline-neutral-950 dark:text-white dark:decoration-white/60 dark:hover:decoration-white dark:data-popup-open:decoration-white dark:focus-visible:outline-white';
</script>

{#snippet typography()}
	<div class="flex w-min flex-col gap-2 p-2">
		<img
			width="224"
			height="150"
			class="block max-w-none"
			src="https://images.unsplash.com/photo-1619615391095-dfa29e1672ef?q=80&w=448&h=300"
			alt="Station Hofplein signage in Rotterdam, Netherlands"
		/>
		<p class="text-sm">
			<strong>Typography</strong> is the art and science of arranging type.
		</p>
	</div>
{/snippet}

{#snippet design()}
	<div class="flex w-min flex-col gap-2 p-2">
		<img
			width="241"
			height="240"
			class="block max-w-none"
			src="https://upload.wikimedia.org/wikipedia/commons/thumb/b/b7/Braun_ABW30_%28schwarz%29.jpg/250px-Braun_ABW30_%28schwarz%29.jpg"
			alt="Braun ABW30"
		/>
		<p class="text-sm">
			A <strong>design</strong> is the concept or proposal for an object, process, or system.
		</p>
	</div>
{/snippet}

{#snippet art()}
	<div class="flex w-min flex-col gap-2 p-2">
		<img
			width="206"
			height="240"
			class="block max-w-none"
			src="https://upload.wikimedia.org/wikipedia/commons/thumb/5/5f/MonaLisa_sfumato.jpeg/250px-MonaLisa_sfumato.jpeg"
			alt="Mona Lisa"
		/>
		<p class="text-sm">
			<strong>Art</strong> is a diverse range of cultural activity centered around works utilizing creative
			or imaginative talents, which are expected to evoke a worthwhile experience, generally through an
			expression of emotional power, conceptual ideas, technical proficiency, or beauty.
		</p>
	</div>
{/snippet}

<div>
	<div class="flex flex-wrap items-baseline justify-center gap-2">
		<p class="text-base text-neutral-950 text-balance dark:text-white">
			Discover
			<PreviewCard.Trigger
				class={linkClass}
				handle={demoPreviewCard}
				href="https://en.wikipedia.org/wiki/Typography"
				id="trigger-1"
				payload={typography}
			>
				typography
			</PreviewCard.Trigger>,
			<PreviewCard.Trigger
				class={linkClass}
				handle={demoPreviewCard}
				href="https://en.wikipedia.org/wiki/Industrial_design"
				id="trigger-2"
				payload={design}
			>
				design
			</PreviewCard.Trigger>, or
			<PreviewCard.Trigger
				class={linkClass}
				handle={demoPreviewCard}
				href="https://en.wikipedia.org/wiki/Art"
				id="trigger-3"
				payload={art}
			>
				art
			</PreviewCard.Trigger>.
		</p>
		<button
			type="button"
			class="flex h-8 items-center justify-center gap-2 border border-neutral-950 bg-white px-3 font-[inherit] text-sm leading-none whitespace-nowrap font-normal text-neutral-950 select-none hover:bg-neutral-100 active:bg-neutral-200 dark:border-white dark:bg-neutral-950 dark:text-white dark:hover:bg-neutral-800 dark:active:bg-neutral-700 disabled:border-neutral-500 disabled:text-neutral-500 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white"
			onclick={() => {
				triggerId = 'trigger-2';
				open = true;
			}}
		>
			Open programmatically
		</button>
	</div>

	<PreviewCard.Root handle={demoPreviewCard} bind:open bind:triggerId>
		{#snippet children({ payload })}
			<PreviewCard.Portal>
				<PreviewCard.Positioner
					sideOffset={8}
					class="h-[var(--positioner-height)] w-[var(--positioner-width)] max-w-[var(--available-width)]"
				>
					<PreviewCard.Popup
						class="relative h-[var(--popup-height,auto)] w-[var(--popup-width,auto)] origin-[var(--transform-origin)] border border-neutral-950 bg-white text-neutral-950 shadow-[0.25rem_0.25rem_0] shadow-black/12 transition-[transform,opacity] duration-100 ease-out data-ending-style:[transform:scale(0.98)] data-ending-style:opacity-0 data-starting-style:[transform:scale(0.98)] data-starting-style:opacity-0 dark:border-white dark:bg-neutral-950 dark:text-white dark:shadow-none"
					>
						<PreviewCard.Arrow
							class="relative block h-1.5 w-3 overflow-clip data-[side=bottom]:top-[-6px] data-[side=left]:right-[-9px] data-[side=left]:rotate-90 data-[side=right]:left-[-9px] data-[side=right]:-rotate-90 data-[side=top]:bottom-[-6px] data-[side=top]:rotate-180 before:absolute before:bottom-0 before:left-1/2 before:h-[calc(6px*sqrt(2))] before:w-[calc(6px*sqrt(2))] before:border before:border-neutral-950 before:bg-white before:content-[''] before:[transform:translate(-50%,50%)_rotate(45deg)] dark:before:border-white dark:before:bg-neutral-950"
						/>
						{@render (payload as Snippet | undefined)?.()}
					</PreviewCard.Popup>
				</PreviewCard.Positioner>
			</PreviewCard.Portal>
		{/snippet}
	</PreviewCard.Root>
</div>

Animating the Preview Card

You can animate a preview card as it moves between different trigger elements. This includes animating its position, size, and content.

Position and Size

To animate the preview card's position, apply CSS transitions to the left, right, top, and bottom properties of the Positioner part. To animate its size, transition the width and height of the Popup part.

Content

The preview card also supports content transitions. This is useful when different triggers display different content within the same preview card.

To enable content animations, wrap the content in the <PreviewCard.Viewport> part. This part provides features to create direction-aware animations. It renders a div with a data-activation-direction attribute that indicates the new trigger's position relative to the previous one. The value is a space-separated set of up to two tokens (one per axis) — left or right for the horizontal axis and up or down for the vertical axis (for example, right down). Match a single token with the ~= attribute selector, such as [data-activation-direction~='right'].

Inside the <PreviewCard.Viewport>, the content is further wrapped in divs with data attributes to help with styling:

data-current: The currently visible content when no transitions are present or the incoming content.
data-previous: The outgoing content during a transition.

You can use these attributes to style the enter and exit animations.

Discover typography, design, or art.

<script lang="ts">
	import type { Snippet } from 'svelte';
	import { PreviewCard } from '@sveltery/base/preview-card';

	const demoPreviewCard = PreviewCard.createHandle<Snippet>();

	const linkClass =
		'text-neutral-950 underline decoration-neutral-950/60 decoration-1 underline-offset-2 outline-0 hover:decoration-neutral-950 data-popup-open:decoration-neutral-950 focus-visible:no-underline focus-visible:outline-2 focus-visible:outline-neutral-950 dark:text-white dark:decoration-white/60 dark:hover:decoration-white dark:data-popup-open:decoration-white dark:focus-visible:outline-white';
</script>

{#snippet typography()}
	<div class="flex w-min flex-col gap-2 p-2">
		<img
			width="224"
			height="150"
			class="block max-w-none"
			src="https://images.unsplash.com/photo-1619615391095-dfa29e1672ef?q=80&w=448&h=300"
			alt="Station Hofplein signage in Rotterdam, Netherlands"
		/>
		<p class="text-sm">
			<strong>Typography</strong> is the art and science of arranging type.
		</p>
	</div>
{/snippet}

{#snippet design()}
	<div class="flex w-min flex-col gap-2 p-2">
		<img
			width="250"
			height="249"
			class="block max-w-none"
			src="https://upload.wikimedia.org/wikipedia/commons/thumb/b/b7/Braun_ABW30_%28schwarz%29.jpg/250px-Braun_ABW30_%28schwarz%29.jpg"
			alt="Braun ABW30"
		/>
		<p class="text-sm">
			A <strong>design</strong> is the concept or proposal for an object, process, or system.
		</p>
	</div>
{/snippet}

{#snippet art()}
	<div class="flex w-min flex-col gap-2 p-2">
		<img
			width="250"
			height="290"
			class="block max-w-none"
			src="https://upload.wikimedia.org/wikipedia/commons/thumb/5/5f/MonaLisa_sfumato.jpeg/250px-MonaLisa_sfumato.jpeg"
			alt="Mona Lisa"
		/>
		<p class="text-sm">
			<strong>Art</strong> is a diverse range of cultural activity centered around works utilizing creative
			or imaginative talents, which are expected to evoke a worthwhile experience, generally through an
			expression of emotional power, conceptual ideas, technical proficiency, or beauty.
		</p>
	</div>
{/snippet}

<div>
	<p class="text-base text-neutral-950 text-balance dark:text-white">
		Discover
		<PreviewCard.Trigger
			class={linkClass}
			handle={demoPreviewCard}
			href="https://en.wikipedia.org/wiki/Typography"
			payload={typography}
		>
			typography
		</PreviewCard.Trigger>,
		<PreviewCard.Trigger
			class={linkClass}
			handle={demoPreviewCard}
			href="https://en.wikipedia.org/wiki/Design"
			payload={design}
		>
			design
		</PreviewCard.Trigger>, or
		<PreviewCard.Trigger
			class={linkClass}
			handle={demoPreviewCard}
			href="https://en.wikipedia.org/wiki/Art"
			payload={art}
		>
			art
		</PreviewCard.Trigger>.
	</p>

	<PreviewCard.Root handle={demoPreviewCard}>
		{#snippet children({ payload })}
			<PreviewCard.Portal>
				<PreviewCard.Positioner
					sideOffset={8}
					class="h-[var(--positioner-height)] w-[var(--positioner-width)] max-w-[var(--available-width)] transition-[top,left,right,bottom,transform] duration-[0.35s] ease-[cubic-bezier(0.22,1,0.36,1)]"
				>
					<PreviewCard.Popup
						class="relative h-[var(--popup-height,auto)] w-[var(--popup-width,auto)] origin-[var(--transform-origin)] border border-neutral-950 bg-white text-neutral-950 shadow-[0.25rem_0.25rem_0] shadow-black/12 transition-[width,height,opacity,transform] duration-[0.35s] ease-[cubic-bezier(0.22,1,0.36,1)] data-ending-style:[transform:scale(0.98)] data-ending-style:opacity-0 data-starting-style:[transform:scale(0.98)] data-starting-style:opacity-0 dark:border-white dark:bg-neutral-950 dark:text-white dark:shadow-none"
					>
						<PreviewCard.Arrow
							class="relative block h-1.5 w-3 overflow-clip data-[side=bottom]:top-[-6px] data-[side=left]:right-[-9px] data-[side=left]:rotate-90 data-[side=right]:left-[-9px] data-[side=right]:-rotate-90 data-[side=top]:bottom-[-6px] data-[side=top]:rotate-180 before:absolute before:bottom-0 before:left-1/2 before:h-[calc(6px*sqrt(2))] before:w-[calc(6px*sqrt(2))] before:border before:border-neutral-950 before:bg-white before:content-[''] before:[transform:translate(-50%,50%)_rotate(45deg)] dark:before:border-white dark:before:bg-neutral-950"
						/>

						<PreviewCard.Viewport
							class="relative overflow-clip w-full h-full [&_[data-previous]]:w-[var(--popup-width)] [&_[data-previous]]:translate-x-0 [&_[data-previous]]:opacity-100 [&_[data-previous]]:transition-[translate,opacity] [&_[data-previous]]:duration-[350ms,175ms] [&_[data-previous]]:ease-[cubic-bezier(0.22,1,0.36,1)] [&_[data-current]]:w-[var(--popup-width)] [&_[data-current]]:translate-x-0 [&_[data-current]]:opacity-100 [&_[data-current]]:transition-[translate,opacity] [&_[data-current]]:duration-[350ms,175ms] [&_[data-current]]:ease-[cubic-bezier(0.22,1,0.36,1)] data-[activation-direction~='left']:[&_[data-current][data-starting-style]]:-translate-x-[30%] data-[activation-direction~='left']:[&_[data-current][data-starting-style]]:opacity-0 data-[activation-direction~='right']:[&_[data-current][data-starting-style]]:translate-x-[30%] data-[activation-direction~='right']:[&_[data-current][data-starting-style]]:opacity-0 data-[activation-direction~='left']:[&_[data-previous][data-ending-style]]:translate-x-[30%] data-[activation-direction~='left']:[&_[data-previous][data-ending-style]]:opacity-0 data-[activation-direction~='right']:[&_[data-previous][data-ending-style]]:-translate-x-[30%] data-[activation-direction~='right']:[&_[data-previous][data-ending-style]]:opacity-0"
						>
							{@render (payload as Snippet | undefined)?.()}
						</PreviewCard.Viewport>
					</PreviewCard.Popup>
				</PreviewCard.Positioner>
			</PreviewCard.Portal>
		{/snippet}
	</PreviewCard.Root>
</div>

API reference

Root

Groups all parts of the preview card. Does not render its own HTML element.

open boolean false

Name: open
Description: Whether the preview card is open. Use bind:open to share it with the parent. A value passed without bind: holds until the parent changes it.
Type: boolean
Default: false
Binding: bind:open

onOpenChange function —

Name: onOpenChange
Description: Called before the open state changes. Call eventDetails.cancel() to veto it.
Type: (open: boolean, details: PreviewCardChangeEventDetails) => void

onOpenChangeComplete function —

Name: onOpenChangeComplete
Description: Called after the open or close transition finishes.
Type: (open: boolean) => void

triggerId string | null —

Name: triggerId
Description: Id of the trigger that owns the preview card. A string wins over the trigger that opened it. An id written by a trigger press resets to null once the popup unmounts.
Type: string | null
Binding: bind:triggerId

handle PreviewCardHandle<Payload> —

Name: handle
Description: Associates detached triggers and imperative open and close.
Type: PreviewCardHandle<Payload>

children Snippet<[{ payload: Payload | undefined }]> —

Name: children
Type: Snippet<[{ payload: Payload | undefined }]>

Trigger

A link that opens the preview card. Renders an <a> element.

handle PreviewCardHandle<Payload> —

Name: handle
Type: PreviewCardHandle<Payload>

payload Payload —

Name: payload
Type: Payload

id string | null —

Name: id
Type: string | null

delay number 600

Name: delay
Description: How long to wait before the preview card opens, in milliseconds.
Type: number
Default: 600

closeDelay number 300

Name: closeDelay
Description: How long to wait before closing the preview card, in milliseconds.
Type: number
Default: 300

render Snippet<[props: HTMLAnchorAttributes, state: PreviewCardTriggerState, children: Snippet | undefined]> —

Name: render
Type: Snippet<[props: HTMLAnchorAttributes, state: PreviewCardTriggerState, children: Snippet | undefined]>

open boolean

Name: open
Description: Whether the preview card is open and was opened by this trigger.
Type: boolean

data-popup-open

Present when the corresponding preview card is open.

Attribute	Description	-
`data-popup-open`	Present when the corresponding preview card is open.

Portal

A portal element that moves the popup to a different part of the DOM. By default, the portal element is appended to <body>.

keepMounted boolean false

Name: keepMounted
Description: Keep the portal mounted while the popup is closed.
Type: boolean
Default: false

container HTMLElement | ShadowRoot | null —

Name: container
Description: Element the portal is appended to. undefined uses the parent portal or document.body. null waits and does not mount until an element or shadow root is set. There is no ref object.
Type: HTMLElement | ShadowRoot | null

render

Snippet<[props: HTMLAttributes<HTMLDivElement> & Record<symbol, Attachment<HTMLDivElement>>, state: PreviewCardPortalState, children: Snippet | undefined]>

—

Name: render
Description: Replace the portal element. The snippet receives host props, an empty state, and the children snippet. Host props include the move attachment.
Type: Snippet<[props: HTMLAttributes<HTMLDivElement> & Record<symbol, Attachment<HTMLDivElement>>, state: PreviewCardPortalState, children: Snippet | undefined]>

Backdrop

A presentational overlay displayed beneath the popup. Renders a <div> element.

render Snippet<[props: HTMLAttributes<HTMLDivElement>, state: PreviewCardBackdropState, children: Snippet | undefined]> —

Name: render
Type: Snippet<[props: HTMLAttributes<HTMLDivElement>, state: PreviewCardBackdropState, children: Snippet | undefined]>

open boolean

Name: open
Type: boolean

transitionStatus 'starting' | 'ending' | 'idle' | undefined

Name: transitionStatus
Type: 'starting' | 'ending' | 'idle' | undefined

data-open

Present when the preview card is open.

data-closed

Present when the preview card is closed.

data-starting-style

Present when the preview card begins animating in.

data-ending-style

Present when the preview card is animating out.

Attribute	Description	-
`data-open`	Present when the preview card is open.
`data-closed`	Present when the preview card is closed.
`data-starting-style`	Present when the preview card begins animating in.
`data-ending-style`	Present when the preview card is animating out.

Positioner

Positions the popup against the trigger. Renders a <div> element.

anchor Anchor —

Name: anchor
Description: An element to position the popup against. By default, the popup will be positioned against the trigger.
Type: Anchor

positionMethod "absolute" | "fixed" 'absolute'

Name: positionMethod
Description: Determines which CSS position property to use.
Type: "absolute" | "fixed"
Default: 'absolute'

side Side 'bottom'

Name: side
Description: Which side of the anchor element to align the popup against. May automatically change to avoid collisions.
Type: Side
Default: 'bottom'

align Align 'center'

Name: align
Description: How to align the popup relative to the specified side.
Type: Align
Default: 'center'

sideOffset number | OffsetFunction 0

Name: sideOffset
Description: Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment.
The function takes a data object parameter with the following properties: - data.anchor: the dimensions of the anchor element with properties width and height. - data.positioner: the dimensions of the positioner element with properties width and height. - data.side: which side of the anchor element the positioner is aligned against. - data.align: how the positioner is aligned relative to the specified side.
Type: number | OffsetFunction
Default: 0

alignOffset number | OffsetFunction 0

Name: alignOffset
Description: Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment.
The function takes a data object parameter with the following properties: - data.anchor: the dimensions of the anchor element with properties width and height. - data.positioner: the dimensions of the positioner element with properties width and height. - data.side: which side of the anchor element the positioner is aligned against. - data.align: how the positioner is aligned relative to the specified side.
Type: number | OffsetFunction
Default: 0

collisionBoundary Boundary 'clipping-ancestors'

Name: collisionBoundary
Description: An element or a rectangle that delimits the area that the popup is confined to.
Type: Boundary
Default: 'clipping-ancestors'

collisionPadding Padding 5

Name: collisionPadding
Description: Additional space to maintain from the edge of the collision boundary.
Type: Padding
Default: 5

arrowPadding number 5

Name: arrowPadding
Description: Minimum distance to maintain between the arrow and the edges of the popup.
Use it to prevent the arrow element from hanging out of the rounded corners of a popup.
Type: number
Default: 5

sticky boolean false

Name: sticky
Description: Whether to maintain the popup in the viewport after the anchor element was scrolled out of view.
Type: boolean
Default: false

disableAnchorTracking boolean false

Name: disableAnchorTracking
Description: Whether to disable the popup from tracking any layout shift of its positioning anchor.
Type: boolean
Default: false

collisionAvoidance CollisionAvoidance —

Name: collisionAvoidance
Description: Determines how to handle collisions when positioning the popup.
side controls overflow on the preferred placement axis (top/bottom or left/right): - 'flip': keep the requested side when it fits; otherwise try the opposite side (top and bottom, or left and right). - 'shift': never change side; keep the requested side and move the popup within the clipping boundary so it stays visible. - 'none': do not correct side-axis overflow.
align controls overflow on the alignment axis (start/center/end): - 'flip': keep side, but swap start and end when the requested alignment overflows. - 'shift': keep side and requested alignment, then nudge the popup along the alignment axis to fit. - 'none': do not correct alignment-axis overflow.
fallbackAxisSide controls fallback behavior on the perpendicular axis when the preferred axis cannot fit: - 'start': allow perpendicular fallback and try the logical start side first (top before bottom, or left before right in LTR). - 'end': allow perpendicular fallback and try the logical end side first (bottom before top, or right before left in LTR). - 'none': do not fallback to the perpendicular axis.
When side is 'shift', explicitly setting align only supports 'shift' or 'none'. If align is omitted, it defaults to 'flip'.
Type: CollisionAvoidance

render Snippet<[props: HTMLAttributes<HTMLDivElement>, state: PreviewCardPositionerState, children: Snippet | undefined]> —

Name: render
Type: Snippet<[props: HTMLAttributes<HTMLDivElement>, state: PreviewCardPositionerState, children: Snippet | undefined]>

open boolean

Name: open
Type: boolean

side Side

Name: side
Type: Side

align Align

Name: align
Type: Align

anchorHidden boolean

Name: anchorHidden
Type: boolean

instant PreviewCardInstant | undefined

Name: instant
Type: PreviewCardInstant | undefined

data-open

Present when the preview card is open.

data-closed

Present when the preview card is closed.

data-anchor-hidden

Present when the anchor is hidden.

data-align

Indicates how the popup is aligned relative to specified side.

data-side

Indicates which side the popup is positioned relative to the trigger.

Attribute	Description	-
`data-open`	Present when the preview card is open.
`data-closed`	Present when the preview card is closed.
`data-anchor-hidden`	Present when the anchor is hidden.
`data-align`	Indicates how the popup is aligned relative to specified side.
`data-side`	Indicates which side the popup is positioned relative to the trigger.

--anchor-height

The anchor's height.

--anchor-width

The anchor's width.

--available-height

The available height between the trigger and the edge of the viewport.

--available-width

The available width between the trigger and the edge of the viewport.

--positioner-height

The height of the preview card's positioner. It is important to set height to this value when using CSS to animate size changes.

--positioner-width

The width of the preview card's positioner. It is important to set width to this value when using CSS to animate size changes.

--transform-origin

The coordinates that this element is anchored to. Used for animations and transitions.

CSS Variable	Description	-
`--anchor-height`	The anchor's height.
`--anchor-width`	The anchor's width.
`--available-height`	The available height between the trigger and the edge of the viewport.
`--available-width`	The available width between the trigger and the edge of the viewport.
`--positioner-height`	The height of the preview card's positioner. It is important to set `height` to this value when using CSS to animate size changes.
`--positioner-width`	The width of the preview card's positioner. It is important to set `width` to this value when using CSS to animate size changes.
`--transform-origin`	The coordinates that this element is anchored to. Used for animations and transitions.

A container for the preview card contents. Renders a <div> element.

render Snippet<[props: HTMLAttributes<HTMLDivElement>, state: PreviewCardPopupState, children: Snippet | undefined]> —

Name: render
Type: Snippet<[props: HTMLAttributes<HTMLDivElement>, state: PreviewCardPopupState, children: Snippet | undefined]>

open boolean

Name: open
Type: boolean

side Side

Name: side
Type: Side

align Align

Name: align
Type: Align

transitionStatus 'starting' | 'ending' | 'idle' | undefined

Name: transitionStatus
Type: 'starting' | 'ending' | 'idle' | undefined

instant PreviewCardInstant | undefined

Name: instant
Type: PreviewCardInstant | undefined

data-open

Present when the preview card is open.

data-closed

Present when the preview card is closed.

data-align

Indicates how the popup is aligned relative to specified side.

data-side

Indicates which side the popup is positioned relative to the trigger.

data-starting-style

Present when the preview card begins animating in.

data-ending-style

Present when the preview card is animating out.

Attribute	Description	-
`data-open`	Present when the preview card is open.
`data-closed`	Present when the preview card is closed.
`data-align`	Indicates how the popup is aligned relative to specified side.
`data-side`	Indicates which side the popup is positioned relative to the trigger.
`data-starting-style`	Present when the preview card begins animating in.
`data-ending-style`	Present when the preview card is animating out.

Viewport

A viewport for displaying content transitions. Renders a <div> element.

render Snippet<[props: HTMLAttributes<HTMLDivElement>, state: PreviewCardViewportState, children: Snippet | undefined]> —

Name: render
Type: Snippet<[props: HTMLAttributes<HTMLDivElement>, state: PreviewCardViewportState, children: Snippet | undefined]>

activationDirection string | undefined

Name: activationDirection
Description: The direction from the previous trigger to the new one, as a horizontal and a vertical value separated by a space. Either value is empty when that axis did not move, so 'right ' and ' down' are valid, as in Base UI.
Type: string | undefined

transitioning boolean

Name: transitioning
Type: boolean

instant PreviewCardInstant | undefined

Name: instant
Type: PreviewCardInstant | undefined

The Viewport is optional — reach for it only when a single popup is opened by multiple triggers, its content differs per trigger, and the switch between them is animated. When used, set width: var(--positioner-width) and height: var(--positioner-height) on the Positioner so its box is frozen to the measured size during the transition; otherwise content-driven resizing can make the popup thrash or flip to another side.

data-activation-direction

Indicates the direction from which the popup was activated. This can be used to create directional animations based on how the popup was triggered. Contains space-separated values for both horizontal and vertical axes.

data-current

Applied to the direct child of the viewport when no transitions are present or the new content when it's entering.

data-instant

Present if animations should be instant.

data-previous

Applied to the direct child of the viewport that contains the exiting content when transitions are present.

data-transitioning

Indicates that the viewport is currently transitioning between old and new content.

Attribute	Description	-
`data-activation-direction`	Indicates the direction from which the popup was activated. This can be used to create directional animations based on how the popup was triggered. Contains space-separated values for both horizontal and vertical axes.
`data-current`	Applied to the direct child of the viewport when no transitions are present or the new content when it's entering.
`data-instant`	Present if animations should be instant.
`data-previous`	Applied to the direct child of the viewport that contains the exiting content when transitions are present.
`data-transitioning`	Indicates that the viewport is currently transitioning between old and new content.

--popup-height

The height of the parent popup. This variable is placed on the 'previous' container and stores the height of the popup when the previous content was rendered. It can be used to freeze the dimensions of the popup when animating between different content.

--popup-width

The width of the parent popup. This variable is placed on the 'previous' container and stores the width of the popup when the previous content was rendered. It can be used to freeze the dimensions of the popup when animating between different content.

CSS Variable	Description	-
`--popup-height`	The height of the parent popup. This variable is placed on the 'previous' container and stores the height of the popup when the previous content was rendered. It can be used to freeze the dimensions of the popup when animating between different content.
`--popup-width`	The width of the parent popup. This variable is placed on the 'previous' container and stores the width of the popup when the previous content was rendered. It can be used to freeze the dimensions of the popup when animating between different content.

Arrow

Displays an element positioned against the preview card anchor. Renders a <div>.

render Snippet<[props: HTMLAttributes<HTMLDivElement>, state: PreviewCardArrowState, children: Snippet | undefined]> —

Name: render
Type: Snippet<[props: HTMLAttributes<HTMLDivElement>, state: PreviewCardArrowState, children: Snippet | undefined]>

open boolean

Name: open
Type: boolean

side Side

Name: side
Type: Side

align Align

Name: align
Type: Align

uncentered boolean

Name: uncentered
Type: boolean

data-open

Present when the preview card is open.

data-closed

Present when the preview card is closed.

data-uncentered

Present when the preview card arrow is uncentered.

data-align

Indicates how the popup is aligned relative to specified side.

data-side

Indicates which side the popup is positioned relative to the trigger.

Attribute	Description	-
`data-open`	Present when the preview card is open.
`data-closed`	Present when the preview card is closed.
`data-uncentered`	Present when the preview card arrow is uncentered.
`data-align`	Indicates how the popup is aligned relative to specified side.
`data-side`	Indicates which side the popup is positioned relative to the trigger.

createHandle

Creates a new handle to connect a PreviewCard.Root with detached PreviewCard.Trigger components.

function createHandle<Payload = unknown>(): PreviewCardHandle<Payload>;

Handle

Controls a PreviewCard imperatively and associates detached PreviewCard.Trigger components with a PreviewCard.Root. Create one with PreviewCard.createHandle() and pass it to the handle prop of the root and of any triggers rendered outside of it.

The imperative methods take effect only while a root using this handle is mounted; calls made before a root attaches (or after it unmounts) are ignored.

Property	Type	Modifiers	Description
`isOpen`	`boolean`	readonly	Whether the preview card is currently open. Returns `false` while no root is attached to the handle.
`payload`	`Payload \\| undefined`	readonly	The payload of the trigger that opened the preview card.

function open(triggerId: string | null): void;

Opens the preview card and associates it with the trigger with the given id. It throws when no trigger with that id is registered, because the preview card needs a trigger to anchor to.

This method should only be called in an event handler or an effect (not during rendering).

function close(): void;

Closes the preview card.

This method should only be called in an event handler or an effect (not during rendering).

function unmount(): void;

Ends the closing phase of the preview card immediately.