Report an issue

Link Preview

Displays a summarized preview of a linked content's details or information.

	<script lang="ts">
  import { Avatar, LinkPreview } from "bits-ui";
  import CalendarBlank from "phosphor-svelte/lib/CalendarBlank";
  import MapPin from "phosphor-svelte/lib/MapPin";
 
  let loadingStatusTrigger: Avatar.RootProps["loadingStatus"] =
    $state("loading");
  let loadingStatusContent: Avatar.RootProps["loadingStatus"] =
    $state("loading");
</script>
 
<LinkPreview.Root>
  <LinkPreview.Trigger
    href="https://github.com/sveltejs"
    target="_blank"
    rel="noreferrer noopener"
    class="rounded-sm underline-offset-4 hover:underline focus-visible:outline-2 focus-visible:outline-offset-8 focus-visible:outline-black"
  >
    <Avatar.Root
      bind:loadingStatus={loadingStatusTrigger}
      class="h-12 w-12 rounded-full border {loadingStatusTrigger === 'loaded'
        ? 'border-foreground'
        : 'border-transparent'} bg-muted text-[17px] font-medium uppercase text-muted-foreground"
    >
      <div
        class="flex h-full w-full items-center justify-center overflow-hidden rounded-full border-2 border-transparent"
      >
        <Avatar.Image src="/avatar-1.png" alt="@huntabyte" />
        <Avatar.Fallback class="border border-muted">HB</Avatar.Fallback>
      </div>
    </Avatar.Root>
  </LinkPreview.Trigger>
  <LinkPreview.Content
    class="w-[331px] rounded-xl border border-muted bg-background p-[17px] shadow-popover"
    sideOffset={8}
  >
    <div class="flex space-x-4">
      <Avatar.Root
        bind:loadingStatus={loadingStatusContent}
        class="h-12 w-12 rounded-full border {loadingStatusContent === 'loaded'
          ? 'border-foreground'
          : 'border-transparent'} bg-muted text-[17px] font-medium uppercase text-muted-foreground"
      >
        <div
          class="flex h-full w-full items-center justify-center overflow-hidden rounded-full border-2 border-transparent"
        >
          <Avatar.Image src="/avatar-1.png" alt="@huntabyte" />
          <Avatar.Fallback class="border border-muted">HB</Avatar.Fallback>
        </div>
      </Avatar.Root>
      <div class="space-y-1 text-sm">
        <h4 class="font-medium">@huntabyte</h4>
        <p>I do things on the internet.</p>
        <div
          class="flex items-center gap-[21px] pt-2 text-xs text-muted-foreground"
        >
          <div class="flex items-center text-xs">
            <MapPin class="mr-1 size-4" />
            <span> FL, USA </span>
          </div>
          <div class="flex items-center text-xs">
            <CalendarBlank class="mr-1 size-4" />
            <span> Joined May 2020</span>
          </div>
        </div>
      </div>
    </div>
  </LinkPreview.Content>
</LinkPreview.Root>

Structure

	<script lang="ts">
	import { LinkPreview } from "bits-ui";
</script>
 
<LinkPreview.Root>
	<LinkPreview.Trigger />
	<LinkPreview.Content />
</LinkPreview.Root>

API Reference

LinkPreview.Root

The root component used to manage the state of the state of the link preview.

Property Type Description
open bindable prop
boolean

The open state of the link preview component.

Default: false
onOpenChange
function

A callback that fires when the open state changes.

Default: undefined
openDelay
number

The amount of time in milliseconds to delay opening the preview when hovering over the trigger.

Default: 700
closeDelay
number

The amount of time in milliseconds to delay closing the preview when the mouse leaves the trigger.

Default: 300
disabled
boolean

Whether or not the link preview is disabled.

Default: false
ignoreNonKeyboardFocus
boolean

Whether the link preview should ignore non-keyboard focus.

Default: false
children
Snippet

The children content to render.

Default: undefined

LinkPreview.Trigger

A component which triggers the opening and closing of the link preview on hover or focus.

Property Type Description
child
Snippet

Use render delegation to render your own element. See render delegation for more information.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
ref
HTMLAnchorElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
Data Attribute Value Description
data-state
enum

The open state of the link preview.

data-link-preview-trigger
——

Present on the trigger element.

LinkPreview.Content

The contents of the link preview which are displayed when the preview is open.

Property Type Description
side
enum

The preferred side of the anchor to render the floating element against when open. Will be reversed when collisions occur.

Default: bottom
sideOffset
number

The distance in pixels from the anchor to the floating element.

Default: 0
align
enum

The preferred alignment of the anchor to render the floating element against when open. This may change when collisions occur.

Default: start
alignOffset
number

The distance in pixels from the anchor to the floating element.

Default: 0
arrowPadding
number

The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.

Default: 0
avoidCollisions
boolean

When true, overrides the side and align options to prevent collisions with the boundary edges.

Default: true
collisionBoundary
union

A boundary element or array of elements to check for collisions against.

Default: undefined
collisionPadding
union

The amount in pixels of virtual padding around the viewport edges to check for overflow which will cause a collision.

Default: 0
sticky
enum

The sticky behavior on the align axis. 'partial' will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst 'always' will keep the content in the boundary regardless.

Default: partial
hideWhenDetached
boolean

When true, hides the content when it is detached from the DOM. This is useful for when you want to hide the content when the user scrolls away.

Default: true
updatePositionStrategy
enum

The strategy to use when updating the position of the content. When 'optimized' the content will only be repositioned when the trigger is in the viewport. When 'always' the content will be repositioned whenever the position changes.

Default: optimized
strategy
enum

The positioning strategy to use for the floating element. When 'fixed' the element will be positioned relative to the viewport. When 'absolute' the element will be positioned relative to the nearest positioned ancestor.

Default: fixed
preventScroll
boolean

When true, prevents the body from scrolling when the content is open. This is useful when you want to use the content as a modal.

Default: true
onInteractOutside
function

Callback fired when an outside interaction event completes, which is either a pointerup, mouseup, or touchend event, depending on the user's input device. You can call event.preventDefault() to prevent the default behavior of handling the outside interaction.

Default: undefined
onInteractOutsideStart
function

Callback fired when an outside interaction event starts, which is either a pointerdown, mousedown, or touchstart event, depending on the user's input device. You can call event.preventDefault() to prevent the continuation of the outside interaction.

Default: undefined
onFocusOutside
function

Callback fired when focus leaves the dismissable layer. You can call event.preventDefault() to prevent the default behavior on focus leaving the layer.

Default: undefined
interactOutsideBehavior
enum

The behavior to use when an interaction occurs outside of the floating content. 'close' will close the content immediately. 'ignore' will prevent the content from closing. 'defer-otherwise-close' will defer to the parent element if it exists, otherwise it will close the content. 'defer-otherwise-ignore' will defer to the parent element if it exists, otherwise it will ignore the interaction.

Default: close
onEscapeKeydown
function

Callback fired when an escape keydown event occurs in the floating content. You can call event.preventDefault() to prevent the default behavior of handling the escape keydown event.

Default: undefined
escapeKeydownBehavior
enum

The behavior to use when an escape keydown event occurs in the floating content. 'close' will close the content immediately. 'ignore' will prevent the content from closing. 'defer-otherwise-close' will defer to the parent element if it exists, otherwise it will close the content. 'defer-otherwise-ignore' will defer to the parent element if it exists, otherwise it will ignore the interaction.

Default: close
onMountAutoFocus
function

Event handler called when auto-focusing the content as it is mounted. Can be prevented.

Default: undefined
onDestroyAutoFocus
function

Event handler called when auto-focusing the content as it is destroyed. Can be prevented.

Default: undefined
dir
enum

The reading direction of the app.

Default: ltr
forceMount
boolean

Whether or not to forcefully mount the content. This is useful if you want to use Svelte transitions or another animnation library for the content.

Default: false
child
Snippet

Use render delegation to render your own element. See render delegation for more information.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
ref
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
Data Attribute Value Description
data-state
enum

The open state of the link preview.

data-link-preview-content
——

Present on the content element.

LinkPreview.Arrow

An optional arrow element which points to the trigger when the preview is open.

Property Type Description
width
number

The width of the arrow in pixels.

Default: 8
height
number

The height of the arrow in pixels.

Default: 8
child
Snippet

Use render delegation to render your own element. See render delegation for more information.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
ref
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
Data Attribute Value Description
data-arrow
——

Present on the arrow element.

data-link-preview-arrow
——

Present on the arrow element.