import { GlobeIcon } from "lucide-react";
import { Citation, CitationContent, CitationDescription, CitationSource, CitationTitle, CitationTrigger,} from "@/components/ui/citation";
const sources = [ { site: "example.com", title: "Custom domains", description: "Add a domain, then point it at your site with a CNAME or A record.", }, { site: "docs.example.org", title: "How DNS propagation works", description: "Resolvers cache records for their TTL, so a change can take up to a day to show.", },];
export default function CitationInline() { return ( <p className="max-w-md text-sm text-foreground"> Point www.example.com at your site with a CNAME record{"\u00a0"} {sources.map((source, index) => ( <Citation key={source.title}> <CitationTrigger href="#" onClick={preventNavigation} aria-label={`Source ${index + 1}: ${source.title}`} > {index + 1} </CitationTrigger> <CitationContent> <CitationSource> <GlobeIcon /> {source.site} </CitationSource> <CitationTitle>{source.title}</CitationTitle> <CitationDescription>{source.description}</CitationDescription> </CitationContent> </Citation> ))} . It usually works within a few minutes. </p> );}- Completed:Add the registryOnce per project
pnpm dlx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json - Completed:Add citation
pnpm dlx shadcn@latest add @jarvis/citation
Usage
import { Citation, CitationContent, CitationDescription, CitationSource, CitationTitle, CitationTrigger,} from "@/components/ui/citation";
export function Cited() { return ( <p> Each key can make 100 requests a minute{" "} <Citation> <CitationTrigger href="https://example.com/docs/rate-limits" aria-label="Source 1: Rate limits" > 1 </CitationTrigger> <CitationContent> <CitationSource>example.com</CitationSource> <CitationTitle>Rate limits</CitationTitle> <CitationDescription>Each API key can make 100 requests a minute.</CitationDescription> </CitationContent> </Citation> . </p> );}A citation is a Hover Card. CitationTrigger is a small numbered link in
the text that opens the source on another site in a new tab. CitationContent previews the source
while someone hovers over or focuses the link. On a touch screen, the first tap shows the preview
and a second tap follows the link.
Give the trigger an aria-label that starts with its number and names the source, such as
Source 1: Rate limits. The number alone doesn't say what the link cites, and a label that
includes the number still matches what voice control users see.
Put a space before the citation, as a model's reply does. The marker stays on the same line as the word before it, and punctuation after the marker stays on its line too. Adjacent markers sit 4px apart.
Composition
Examples
In a reply
Models cite sources with numbered links, such as [1](https://example.com/docs/rate-limits). Pass
Markdown a link component that renders a citation for each URL you have a
source for and falls back to MarkdownLink for the rest. The AI SDK sends the sources a reply used
as source-url parts, each with a url and title. TanStack AI doesn't send sources, so take them
from the output of the tool that found them.
import { GlobeIcon } from "lucide-react";
import { Citation, CitationContent, CitationDescription, CitationSource, CitationTitle, CitationTrigger,} from "@/components/ui/citation";import { Markdown, MarkdownLink } from "@/components/ui/markdown";
const sources = [ { url: "https://example.com/docs/rate-limits", site: "example.com", title: "Rate limits", description: "Each API key can make 100 requests a minute, with bursts of up to 20 a second.", }, { url: "https://example.com/docs/errors", site: "example.com", title: "Errors", description: "A 429 response means you’ve hit a limit. Wait for the Retry-After header.", },];
const reply = `You can make **100 requests a minute** with each key [1](https://example.com/docs/rate-limits). Past that, the API answers with a \`429\` and a \`Retry-After\` header saying how long to wait [2](https://example.com/docs/errors).`;
function Link(props: React.ComponentProps<"a">) { const index = sources.findIndex((source) => source.url === props.href); const source = sources[index]; if (!source) return <MarkdownLink {...props} />;
return ( <Citation> <CitationTrigger href={props.href} onClick={preventNavigation} aria-label={`Source ${index + 1}: ${source.title}`} > {props.children} </CitationTrigger> <CitationContent> <CitationSource> <GlobeIcon /> {source.site} </CitationSource> <CitationTitle>{source.title}</CitationTitle> <CitationDescription>{source.description}</CitationDescription> </CitationContent> </Citation> );}
const components = { a: Link };
export default function CitationInMarkdown() { return ( <Markdown components={components} className="w-full max-w-md"> {reply} </Markdown> );}To list every source a reply read, use an expandable Trace line.
Props
Base UI's styling (opens in a new tab) and composition (opens in a new tab) guides say more about className, style and render.
Citation
| Prop | Type | Default |
|---|---|---|
defaultOpenWhether the preview card is initially open. To render a controlled preview card, use the | boolean | false |
openWhether the preview card is currently open. | boolean | — |
onOpenChangeEvent handler called when the preview card is opened or closed. | ((open: boolean, eventDetails: PreviewCardRoot.ChangeEventDetails) => void) | — |
onOpenChangeCompleteEvent handler called after any animations complete when the preview card is opened or closed. | ((open: boolean) => void) | — |
actionsRefA ref to imperative actions.
| React.RefObject<PreviewCardRootActions | null> | — |
handleA handle to associate the preview card with a trigger. If specified, allows external triggers to control the card's open state. Can be created with the PreviewCard.createHandle() method. | PreviewCardHandle<unknown> | — |
childrenThe content of the preview card.
This can be a regular React node or a render function that receives the | PayloadChildRenderFunction<unknown> | React.ReactNode | — |
triggerIdID of the trigger that the preview card is associated with.
This is useful in conjunction with the | string | null | — |
defaultTriggerIdID of the trigger that the preview card is associated with.
This is useful in conjunction with the | string | null | — |
CitationTrigger
| Prop | Type | Default |
|---|---|---|
handleA handle to associate the trigger with a preview card. | PreviewCardHandle<unknown> | — |
payloadA payload to pass to the preview card when it is opened. | unknown | — |
delayHow long to wait before the preview card opens. Specified in milliseconds. | number | 600 |
closeDelayHow long to wait before closing the preview card. Specified in milliseconds. | number | 300 |
openOnTapOpens the card when the trigger is tapped on a touch screen, where hovering can't open it. A second tap follows the link, and a tap elsewhere closes the card. | boolean | true |
newTabLabelWhat screen readers announce after a source on another site, which opens in a new tab. Pass an empty string to announce nothing. | string | "(opens in a new tab)" |
classNameCSS class applied to the element, or a function that returns a class based on the component's state. | string | ((state: PreviewCardTriggerState) => string | undefined) | — |
styleStyle applied to the element, or a function that returns a style object based on the component's state. | React.CSSProperties | ((state: PreviewCardTriggerState) => React.CSSProperties | undefined) | — |
renderAllows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a | ComponentRenderFn<React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, PreviewCardTriggerState> | React.ReactElement | — |
CitationContent
| Prop | Type | Default |
|---|---|---|
keepMountedWhether to keep the portal mounted in the DOM while the popup is hidden. | boolean | false |
containerA parent element to render the portal element into. | HTMLElement | React.RefObject<HTMLElement | ShadowRoot | null> | ShadowRoot | null | — |
anchorAn element to position the popup against. By default, the popup will be positioned against the trigger. | Element | React.RefObject<Element | null> | VirtualElement | (() => Element | VirtualElement | null) | null | — |
positionMethodDetermines which CSS | "absolute" | "fixed" | 'absolute' |
sideWhich side of the anchor element to align the popup against. May automatically change to avoid collisions. | "bottom" | "inline-end" | "inline-start" | "left" | "right" | "top" | "bottom" |
sideOffsetDistance 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
| number | OffsetFunction | 4 |
alignHow to align the popup relative to the specified side. | "center" | "end" | "start" | "start" |
alignOffsetAdditional 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
| number | OffsetFunction | 0 |
collisionBoundaryAn element or a rectangle that delimits the area that the popup is confined to. | Boundary | 'clipping-ancestors' |
collisionPaddingAdditional space to maintain from the edge of the collision boundary. | Padding | 5 |
stickyWhether to maintain the popup in the viewport after the anchor element was scrolled out of view. | boolean | false |
arrowPaddingMinimum 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. | number | 5 |
disableAnchorTrackingWhether to disable the popup from tracking any layout shift of its positioning anchor. | boolean | false |
collisionAvoidanceDetermines how to handle collisions when positioning the popup.
When | CollisionAvoidance | — |
classNameCSS class applied to the element, or a function that returns a class based on the component's state. | string | ((state: PreviewCardPopupState) => string | undefined) | — |
styleStyle applied to the element, or a function that returns a style object based on the component's state. | React.CSSProperties | ((state: PreviewCardPopupState) => React.CSSProperties | undefined) | — |
renderAllows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a | ComponentRenderFn<HTMLProps, PreviewCardPopupState> | React.ReactElement | — |
CitationSource
| Prop | Type | Default |
|---|---|---|
classNameCSS class applied to the element. | string | — |
styleStyle applied to the element. | React.CSSProperties | — |
renderAllows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a | ComponentRenderFn<HTMLProps, {}> | React.ReactElement | — |
CitationTitle
| Prop | Type | Default |
|---|---|---|
classNameCSS class applied to the element. | string | — |
styleStyle applied to the element. | React.CSSProperties | — |
renderAllows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a | ComponentRenderFn<HTMLProps, {}> | React.ReactElement | — |
CitationDescription
| Prop | Type | Default |
|---|---|---|
classNameCSS class applied to the element. | string | — |
styleStyle applied to the element. | React.CSSProperties | — |
renderAllows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a | ComponentRenderFn<HTMLProps, {}> | React.ReactElement | — |