`: a paragraph cannot legally hold it. ::component-preview{name="PreviewCardPreview"} ```vue ``` :: ## Usage guidelines - Put everything the card shows behind the link as well. The card is never announced to a screen reader and never reachable on touch, so nothing in it can be the only way to that information. - Keep the trigger a link. If the preview hangs off a button, use [`Popover`](/components/popover); if it only shows a label, use [`Tooltip`](/components/tooltip). - Leave `delay` where it is unless you have a reason. Six hundred milliseconds is long enough that a pointer crossing the link on its way somewhere else does not open anything. - `PreviewCard.Content` teleports to the end of `` unless you turn that off with `options.portal.disabled`. Leave it on where the link sits inside anything with `overflow: hidden`. - The content resolves everything but `side` and `align` once, during setup, so change the rest before the popup first renders or key the root to remount it. ## Anatomy Assemble the parts. `PreviewCard.Content` is one part over three boxes: the teleport, the floating box and the popup, plus a backdrop under `options.backdrop`. Everything you put inside it renders in the popup. ::component-anatomy --- parts: - name: PreviewCard.Root required: true description: 'Renders nothing of its own. It is the provider.' children: - name: PreviewCard.Trigger required: true description: 'Renders an . The card hangs off it and is positioned against it.' - name: PreviewCard.Content required: true description: 'Renders the teleport, the floating box and the popup.' children: - name: PreviewCard.Arrow description: 'Optional. Renders a

pointing at the trigger.' --- :: ```vue ``` ## Examples ### Timing `delay` is how long the pointer has to rest on the link before the card opens, `closeDelay` how long it has to be away before it closes again. The close delay is what lets the pointer travel from the link to the card without the card disappearing under it, so shortening it much below the default makes the card hard to reach. ```vue ``` Both also exist as props on the trigger, for a single link that wants to behave differently from the rest. ```vue ``` ### Positioning `PreviewCard.Content` reads `options.floating` and writes the resolved side and alignment back as `data-side` and `data-align`; read those rather than the options you passed, since flipping can change either one. ```vue ``` Pass `anchor` to position against something else, and pass any of the eight floating keys straight to the content to override the options for one instance. ```vue ``` The content writes `--rack-floating-anchor-width`, `--rack-floating-anchor-height`, `--rack-floating-available-width`, `--rack-floating-available-height` and `--rack-floating-transform-origin` onto the floating box, so an unstyled popup is never taller than the space around the link. Add a `PreviewCard.Arrow` inside the content and it is placed by the same middleware run, against the same anchor. It writes `--rack-arrow-x` and `--rack-arrow-y`, so its own stylesheet can point it the right way per side. ```css .arrow[data-side='bottom'] { top: -6px; rotate: 180deg; } ``` ### Where the card renders The content teleports to the end of ``, which is what keeps a card out of an ancestor’s `overflow: hidden` and above the rest of the page. Turn it off to render in place, or name a target of your own. ```vue ``` `options.backdrop` adds a fixed `

` behind the card. It takes no pointer events by default, since the pointer has to travel from the link to the popup, and it has no dismiss behaviour of its own: the popup’s layer already closes on a pointer down outside. ```vue ``` ### Animating it Name a transition and the popup runs it on the way in and out. The backdrop takes its own. ```vue ``` ```css .card-enter-active, .card-leave-active { transition: opacity 150ms ease-out; } .card-enter-from, .card-leave-to { opacity: 0; } ``` Without a name the popup unmounts as it closes. For a keyframe animation rather than a transition, read `data-state`, which is `open` or `closed` for as long as the popup is rendered, and the popup waits for the animation to end before it goes. ```css .popup[data-state='closed'] { animation: fade-out 150ms ease-in; } ``` [Animation](/components/animation) has both patterns in full. ### Reaching the card from anywhere Give the root an `id` and `useMirrorPreviewCard(id)` opens, closes and reads that card from anywhere in the app. ```vue ``` ### Styling from state Every part writes its state to `data-*`, so style it with attribute selectors. ```css .trigger[data-popup-open='true'] { text-decoration-style: dotted; } .popup[data-side='top'] { transform-origin: bottom center; } ``` The content’s boxes are not parts, so they are reached by their `data-scope` or by the class each one ships. A `class` on `PreviewCard.Content` is applied to the popup, the box you paint. ```vue ``` ```css .mirror-preview-card-floating { --mirror-preview-card-floating-z-index: 80; } [data-scope='floating'][data-anchor-hidden='true'] { visibility: hidden; } ``` ## API reference **Module.** A bundled `options` object on the root, and `useMirrorPreviewCard(id)` as the programmatic API. Every part takes `id` to resolve a card it is not nested inside. ### `PreviewCard.Root` Renders its children. It is a provider and has no element of its own. #### Props ::docs-table --- columns: - label: Prop - label: Type - label: Default rows: - items: - label: id description: '[The instance ID](#reaching-the-card-from-anywhere).' - label: string - label: generated plaintext: true - items: - label: open description: Open state. `v-model:open`. - label: 'boolean | undefined' - label: undefined - items: - label: defaultOpen description: 'Initial open state when [uncontrolled](/components/composition#controlled-and-uncontrolled).' - label: boolean - label: 'false' - items: - label: options description: Everything else. Deep-merged over the defaults. - label: PreviewCardOptions - label: see below plaintext: true --- :: #### Options ::docs-table --- columns: - label: Option - label: Type - label: Default rows: - items: - label: delay description: 'Milliseconds the pointer rests on the trigger before it [opens](#timing).' - label: number - label: '600' - items: - label: closeDelay description: 'Milliseconds the pointer is away before it [closes](#timing).' - label: number - label: '300' - items: - label: disabled description: Refuses to open, by pointer and by keyboard alike. - label: boolean - label: 'false' - items: - label: forceMount description: Keeps the popup and the backdrop mounted while closed. - label: boolean - label: 'false' - items: - label: backdrop description: Renders a fixed `

` behind the card. - label: boolean - label: 'false' - items: - label: dismiss.escape description: Escape closes the card. - label: boolean - label: 'true' - items: - label: dismiss.pointerDownOutside description: A pointer down outside closes the card. - label: boolean - label: 'true' - items: - label: dismiss.focusOutside description: Focus leaving closes the card. - label: boolean - label: 'true' - items: - label: portal.to description: The teleport target. - label: 'string | HTMLElement' - label: body plaintext: true - items: - label: portal.disabled description: Renders in place instead. - label: boolean - label: 'false' - items: - label: portal.defer description: Resolves the target after mount, for a target rendered by the same app. - label: boolean - label: 'false' - items: - label: floating.side description: Preferred side. Reactive. - label: '''top'' | ''right'' | ''bottom'' | ''left''' - label: '''bottom''' - items: - label: floating.sideOffset description: Gap from the trigger, in pixels. - label: number - label: '8' - items: - label: floating.align description: Alignment along that side. Reactive. - label: '''start'' | ''center'' | ''end''' - label: '''center''' - items: - label: floating.alignOffset description: Shift along the alignment axis, in pixels. - label: number - label: '0' - items: - label: floating.strategy description: Positioning strategy. - label: '''absolute'' | ''fixed''' - label: '''absolute''' - items: - label: floating.flip description: Flip to the opposite side when there is no room. - label: boolean - label: 'true' - items: - label: floating.shift description: Slide along the side to stay in view. - label: boolean - label: 'true' - items: - label: floating.collisionPadding description: Padding used by flipping and shifting. - label: number - label: '8' - items: - label: transition.popup description: Vue transition name for the popup. - label: string - label: undefined - items: - label: transition.backdrop description: Vue transition name for the backdrop. - label: string - label: undefined --- :: #### Emits ::docs-table --- columns: - label: Emit - label: Payload rows: - items: - label: update:open description: The card opens or closes. - label: boolean - items: - label: openChange description: The card opens or closes, with what caused it. - label: '(value: boolean, reason: PreviewCardOpenReason)' --- :: `PreviewCardOpenReason` is `trigger-hover`, `trigger-focus`, `trigger-press`, `outside-press`, `escape-key`, `imperative-action` or `none`. #### Slot props ::docs-table --- columns: - label: Prop - label: Type rows: - items: - label: open description: The card is open. - label: boolean - items: - label: side description: Mirrors `data-side`. - label: 'PreviewCardSide | undefined' - items: - label: align description: Mirrors `data-align`. - label: 'PreviewCardAlign | undefined' --- :: ### `PreviewCard.Trigger` Renders an ``. It is the anchor the card is positioned against, and it stays an ordinary link: pressing it navigates and closes the card. #### Props ::docs-table --- columns: - label: Prop - label: Type - label: Default rows: - items: - label: delay description: Escape hatch over `options.delay`. - label: number - label: options.delay - items: - label: closeDelay description: Escape hatch over `options.closeDelay`. - label: number - label: options.closeDelay --- :: #### Slot props ::docs-table --- columns: - label: Prop - label: Type rows: - items: - label: open description: Mirrors `data-popup-open`. - label: boolean - items: - label: side description: Mirrors `data-side`. - label: 'PreviewCardSide | undefined' - items: - label: align description: Mirrors `data-align`. - label: 'PreviewCardAlign | undefined' --- :: ### `PreviewCard.Content` Renders everything that floats: the teleport, the floating box and the popup, plus a backdrop under `options.backdrop`. Everything in its default slot renders inside the popup. It anchors on `PreviewCard.Trigger`, and it keeps the card open while the pointer is over the popup. It never takes focus. #### Layers None of the boxes is a part, so each is styled through its `data-scope` or the class it ships. A `class` on the content itself is applied to the popup. ::docs-table --- columns: - label: Layer - label: Element - label: Publishes rows: - items: - label: portal description: The teleport. Configured through `options.portal`. - label: none plaintext: true - label: nothing plaintext: true - items: - label: backdrop description: '`.mirror-preview-card-backdrop`, only under `options.backdrop`.' - label: 'div[role=presentation]' - label: '`data-preview-card`, `data-state`' plaintext: true - items: - label: floating description: '`.mirror-preview-card-floating`. Carries the floating styles and the `--rack-floating-*` set.' - label: div - label: '`data-side`, `data-align`, `data-anchor-hidden`, `data-state`' plaintext: true - items: - label: popup description: '`.mirror-preview-card-popup`. Presence and dismissal live here, and the pointer resting on it keeps the card open.' - label: div - label: '`data-preview-card`, `data-side`, `data-align`, `data-state`' plaintext: true --- :: #### Props Every prop below but `forceMount` and `anchor` is an escape hatch over the matching `options.floating` key, and only `side` and `align` stay reactive after mount. `forceMount` is the hatch over `options.forceMount`. ::docs-table --- columns: - label: Prop - label: Type - label: Default rows: - items: - label: forceMount description: Keeps the popup and the backdrop mounted while closed. - label: boolean - label: options.forceMount - items: - label: anchor description: Position against this element instead. - label: 'HTMLElement | (() => HTMLElement | null)' - label: the trigger plaintext: true - items: - label: side description: Preferred side. - label: '''top'' | ''right'' | ''bottom'' | ''left''' - label: '''bottom''' - items: - label: sideOffset description: Gap from the trigger, in pixels. - label: number - label: '8' - items: - label: align description: Alignment along that side. - label: '''start'' | ''center'' | ''end''' - label: '''center''' - items: - label: alignOffset description: Shift along the alignment axis, in pixels. - label: number - label: '0' - items: - label: strategy description: Positioning strategy. - label: '''absolute'' | ''fixed''' - label: '''absolute''' - items: - label: flip description: Flip to the opposite side when there is no room. - label: boolean - label: 'true' - items: - label: shift description: Slide along the side to stay in view. - label: boolean - label: 'true' - items: - label: collisionPadding description: Padding used by flipping and shifting. - label: number - label: '8' --- :: #### Slot props ::docs-table --- columns: - label: Prop - label: Type rows: - items: - label: open description: Mirrors `data-state`. - label: boolean - items: - label: side description: Resolved after collision handling. - label: PreviewCardSide - items: - label: align description: Resolved after collision handling. - label: PreviewCardAlign --- :: ### `PreviewCard.Arrow` Renders a `