Retrieved Context Chunks
The RAG debugging surface: ranked passages with similarity as a meter, matched spans in real mark elements, and filter chips wired as a radiogroup so arrows move between them.
The refusal screen: says plainly that nothing was found, shows where it looked and the near-misses below threshold, and offers the two real ways out instead of inventing an answer.
components/retrieval-empty-state.tsxnpx hoverlab add retrieval-empty-state
Or over MCP, from your editor's agent — no account needed.
Free to read, copy and install, for personal and non-commercial projects. Shipping it in client work or a paid product needs Pro ($79 once). The source lands in your repo and stops being ours — no attribution, nothing to upgrade.
Start a page with this section — add more, order them, and leave with the page source.
Rather than guess at a number that has to be exact, here is where I looked and what came closest.
what is our EU VAT registration number
Tax registrations usually live in the finance drive, which is not connected.
Rendered live in your current theme — this is the same component whose source is below, not a screenshot of it.
/**
* <RetrievalEmptyState> — what an assistant says when it found nothing, and
* refuses to invent an answer.
*
* The most valuable screen in a RAG product and the one nobody designs. The
* default failure is a model that pads the gap with something plausible; the
* design job is to make "I don't know" feel like competence rather than a
* dead end.
*
* Structure of an honest miss:
*
* 1. Say plainly that nothing was found — not "no results", which reads as
* a broken search.
* 2. Show *where it looked*, so the user can see the gap is in coverage
* rather than in the question. This is what converts frustration into a
* next action.
* 3. Offer the near-misses that scored too low to use, with their scores,
* rather than discarding them silently.
* 4. Offer the two real ways out: broaden the search, or connect the source
* that would have had the answer.
*
* `role="status"`, not `role="alert"` — an empty result is information, not
* an emergency, and assertive announcements interrupt whatever the user is
* reading. The heading is the first thing in the region so it is what gets
* read.
*/
import * as React from 'react'
import { Database, FileQuestion, FileText, Globe, Plus, RefreshCw, Search } from 'lucide-react'
export interface SearchedScope {
id: string
label: string
detail: string
kind: 'doc' | 'table' | 'web'
}
export interface NearMiss {
id: string
title: string
score: number
}
export interface RetrievalEmptyStateProps {
query?: string
headline?: string
body?: string
searched?: SearchedScope[]
nearMisses?: NearMiss[]
/** The gap the user could close, named specifically. */
suggestion?: string
className?: string
}
const KIND_ICON = {
doc: FileText,
table: Database,
web: Globe,
} as const
const DEFAULT_SEARCHED: SearchedScope[] = [
{ id: '1', label: 'Company handbook', detail: '214 documents', kind: 'doc' },
{ id: '2', label: 'Analytics warehouse', detail: '18 tables', kind: 'table' },
{ id: '3', label: 'help.acme.com', detail: '480 pages', kind: 'web' },
]
const DEFAULT_NEAR_MISSES: NearMiss[] = [
{ id: '1', title: 'Refund policy for annual plans', score: 0.31 },
{ id: '2', title: 'Ticket #3820 — chargeback process', score: 0.28 },
]
export function RetrievalEmptyState({
query = 'what is our EU VAT registration number',
headline = 'I could not find this in anything I can read.',
body = 'Rather than guess at a number that has to be exact, here is where I looked and what came closest.',
searched = DEFAULT_SEARCHED,
nearMisses = DEFAULT_NEAR_MISSES,
suggestion = 'Tax registrations usually live in the finance drive, which is not connected.',
className = '',
}: RetrievalEmptyStateProps) {
return (
<section
role="status"
className={`mx-auto w-full max-w-xl rounded-2xl border border-border/60 bg-card p-6 ${className}`}
>
<div className="text-center">
<span className="inline-flex h-12 w-12 items-center justify-center rounded-2xl bg-muted text-muted-foreground">
<FileQuestion aria-hidden className="h-5 w-5" />
</span>
{headline ? (
<h3 data-stress-ignore className="mt-4 text-balance text-base font-semibold">{headline}</h3>
) : null}
<p className="mx-auto mt-2 max-w-sm text-pretty text-sm leading-relaxed text-muted-foreground">
{body}
</p>
<p className="mt-3 inline-flex max-w-full items-center gap-1.5 rounded-full border border-border/60 bg-muted/40 px-2.5 py-1.5">
<Search aria-hidden className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
<span className="min-w-0 truncate font-mono text-xs text-muted-foreground">{query}</span>
</p>
</div>
{/* -- Where it looked --------------------------------------------- */}
<div className="mt-6">
<h4 data-stress-ignore className="mb-2 text-xs font-bold uppercase tracking-wider text-muted-foreground">
Searched
</h4>
<ul className="space-y-1.5">
{searched.map((scope) => {
const Icon = KIND_ICON[scope.kind]
return (
<li
key={scope.id}
className="flex items-center gap-2.5 rounded-xl border border-border/60 px-3 py-2 text-xs"
>
<Icon aria-hidden className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
<span className="min-w-0 flex-1 truncate font-medium">{scope.label}</span>
<span className="ms-auto shrink-0 text-muted-foreground">{scope.detail}</span>
<span className="shrink-0 text-muted-foreground">· 0 matches</span>
</li>
)
})}
</ul>
</div>
{/* -- Near misses -------------------------------------------------- */}
{nearMisses.length > 0 ? (
<div className="mt-5">
<h4 data-stress-ignore className="mb-2 text-xs font-bold uppercase tracking-wider text-muted-foreground">
Closest, but below the threshold
</h4>
<ul className="space-y-1.5">
{nearMisses.map((miss) => (
<li key={miss.id}>
<button
type="button"
className="flex w-full items-center gap-2.5 rounded-xl px-3 py-2 text-start text-xs transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
>
<span className="truncate">{miss.title}</span>
<span className="ms-auto shrink-0 font-mono text-[11px] tabular-nums text-muted-foreground">
{miss.score.toFixed(2)}
<span className="sr-only"> similarity, below the 0.45 cutoff</span>
</span>
</button>
</li>
))}
</ul>
</div>
) : null}
{/* -- The two ways out --------------------------------------------- */}
{suggestion ? (
<p className="mt-5 rounded-xl bg-muted/40 px-3.5 py-2.5 text-xs leading-relaxed text-muted-foreground">
{suggestion}
</p>
) : null}
<div className="mt-4 flex flex-col gap-2 sm:flex-row">
<button
type="button"
className="inline-flex flex-1 items-center justify-center gap-1.5 rounded-xl border border-border/60 px-3.5 py-2.5 text-sm font-medium transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
>
<RefreshCw aria-hidden className="h-4 w-4" />
Search without the cutoff
</button>
<button
type="button"
className="inline-flex flex-1 items-center justify-center gap-1.5 rounded-xl bg-primary px-3.5 py-2.5 text-sm font-semibold text-primary-foreground transition-opacity hover:opacity-90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"
>
<Plus aria-hidden className="h-4 w-4" />
Connect a source
</button>
</div>
</section>
)
}
bg-card, text-muted-foreground) — it inherits your theme instead of overriding it.Drop it at components/retrieval-empty-state.tsx and import it where you need the section:
import { RetrievalEmptyState } from '@/components/retrieval-empty-state'3 of this block’s props are simple enough to drive from here. Change them and the block below re-renders — it is the same component whose source is above, not a mock of it. Everything else it accepts is in the table underneath.
Read out of the component’s own type and signature, so this cannot drift from the source below. Every prop has a default — the component renders standalone before you pass it anything.
| Prop | Type | Default |
|---|---|---|
query | string | 'what is our EU VAT registration number' |
headline | string | 'I could not find this in anything I can read.' |
body | string | — |
searched | SearchedScope[] | DEFAULT_SEARCHED |
nearMisses | NearMiss[] | DEFAULT_NEAR_MISSES |
suggestionThe gap the user could close, named specifically. | string | 'Tax registrations usually live in the financ… |
className | string | '' |
The same block rendered once to markup, wrapped as a file your framework compiles. Tailwind classes are framework-agnostic, so the design transfers intact — the behaviour does not.
<!--
Nothing Found, Answered Honestly — markup from the Hoverlab catalog.
This is the block rendered once to HTML and wrapped as a component
file. It is not a port of the React source: the Tailwind classes carry
the design, which is the part that took the work, and they are the same
in every framework.
This block has no interactive behaviour, so nothing is missing.
-->
<section role="status" class="mx-auto w-full max-w-xl rounded-2xl border border-border/60 bg-card p-6 ">
<div class="text-center">
<span class="inline-flex h-12 w-12 items-center justify-center rounded-2xl bg-muted text-muted-foreground">
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-file-question-mark h-5 w-5" aria-hidden="true">
<path d="M12 17h.01"></path>
<path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7z"></path>
<path d="M9.1 9a3 3 0 0 1 5.82 1c0 2-3 3-3 3"></path>
</svg>
</span>
<h3 data-stress-ignore="true" class="mt-4 text-balance text-base font-semibold">I could not find this in anything I can read.</h3>
<p class="mx-auto mt-2 max-w-sm text-pretty text-sm leading-relaxed text-muted-foreground">Rather than guess at a number that has to be exact, here is where I looked and what came closest.</p>
<p class="mt-3 inline-flex max-w-full items-center gap-1.5 rounded-full border border-border/60 bg-muted/40 px-2.5 py-1.5">
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-search h-3.5 w-3.5 shrink-0 text-muted-foreground" aria-hidden="true">
<path d="m21 21-4.34-4.34"></path>
<circle cx="11" cy="11" r="8"></circle>
</svg>
<span class="min-w-0 truncate font-mono text-xs text-muted-foreground">what is our EU VAT registration number</span>
</p>
</div>
<div class="mt-6">
<h4 data-stress-ignore="true" class="mb-2 text-xs font-bold uppercase tracking-wider text-muted-foreground">Searched</h4>
<ul class="space-y-1.5">
<li class="flex items-center gap-2.5 rounded-xl border border-border/60 px-3 py-2 text-xs">
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-file-text h-3.5 w-3.5 shrink-0 text-muted-foreground" aria-hidden="true">
<path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z"></path>
<path d="M14 2v4a2 2 0 0 0 2 2h4"></path>
<path d="M10 9H8"></path>
<path d="M16 13H8"></path>
<path d="M16 17H8"></path>
</svg>
<span class="min-w-0 flex-1 truncate font-medium">Company handbook</span>
<span class="ms-auto shrink-0 text-muted-foreground">214 documents</span>
<span class="shrink-0 text-muted-foreground">· 0 matches</span>
</li>
<li class="flex items-center gap-2.5 rounded-xl border border-border/60 px-3 py-2 text-xs">
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-database h-3.5 w-3.5 shrink-0 text-muted-foreground" aria-hidden="true">
<ellipse cx="12" cy="5" rx="9" ry="3"></ellipse>
<path d="M3 5V19A9 3 0 0 0 21 19V5"></path>
<path d="M3 12A9 3 0 0 0 21 12"></path>
</svg>
<span class="min-w-0 flex-1 truncate font-medium">Analytics warehouse</span>
<span class="ms-auto shrink-0 text-muted-foreground">18 tables</span>
<span class="shrink-0 text-muted-foreground">· 0 matches</span>
</li>
<li class="flex items-center gap-2.5 rounded-xl border border-border/60 px-3 py-2 text-xs">
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-globe h-3.5 w-3.5 shrink-0 text-muted-foreground" aria-hidden="true">
<circle cx="12" cy="12" r="10"></circle>
<path d="M12 2a14.5 14.5 0 0 0 0 20 14.5 14.5 0 0 0 0-20"></path>
<path d="M2 12h20"></path>
</svg>
<span class="min-w-0 flex-1 truncate font-medium">help.acme.com</span>
<span class="ms-auto shrink-0 text-muted-foreground">480 pages</span>
<span class="shrink-0 text-muted-foreground">· 0 matches</span>
</li>
</ul>
</div>
<div class="mt-5">
<h4 data-stress-ignore="true" class="mb-2 text-xs font-bold uppercase tracking-wider text-muted-foreground">Closest, but below the threshold</h4>
<ul class="space-y-1.5">
<li>
<button type="button" class="flex w-full items-center gap-2.5 rounded-xl px-3 py-2 text-start text-xs transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring">
<span class="truncate">Refund policy for annual plans</span>
<span class="ms-auto shrink-0 font-mono text-[11px] tabular-nums text-muted-foreground">0.31<span class="sr-only"> similarity, below the 0.45 cutoff</span></span>
</button>
</li>
<li>
<button type="button" class="flex w-full items-center gap-2.5 rounded-xl px-3 py-2 text-start text-xs transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring">
<span class="truncate">Ticket #3820 — chargeback process</span>
<span class="ms-auto shrink-0 font-mono text-[11px] tabular-nums text-muted-foreground">0.28<span class="sr-only"> similarity, below the 0.45 cutoff</span></span>
</button>
</li>
</ul>
</div>
<p class="mt-5 rounded-xl bg-muted/40 px-3.5 py-2.5 text-xs leading-relaxed text-muted-foreground">Tax registrations usually live in the finance drive, which is not connected.</p>
<div class="mt-4 flex flex-col gap-2 sm:flex-row">
<button type="button" class="inline-flex flex-1 items-center justify-center gap-1.5 rounded-xl border border-border/60 px-3.5 py-2.5 text-sm font-medium transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-refresh-cw h-4 w-4" aria-hidden="true"><path d="M3 12a9 9 0 0 1 9-9 9.75 9.75 0 0 1 6.74 2.74L21 8"></path><path d="M21 3v5h-5"></path><path d="M21 12a9 9 0 0 1-9 9 9.75 9.75 0 0 1-6.74-2.74L3 16"></path><path d="M8 16H3v5"></path></svg>Search without the cutoff</button>
<button type="button" class="inline-flex flex-1 items-center justify-center gap-1.5 rounded-xl bg-primary px-3.5 py-2.5 text-sm font-semibold text-primary-foreground transition-opacity hover:opacity-90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-plus h-4 w-4" aria-hidden="true"><path d="M5 12h14"></path><path d="M12 5v14"></path></svg>Connect a source</button>
</div>
</section>
What each framework gets across the whole catalog — effects convert properly; this rung is markup.
The component, its props, the design tokens it expects and the command that installs it — as one prompt. Paste it into Claude, Cursor, v0 or ChatGPT and what they build around it will match the rest of the catalog instead of inventing its own system.
Want the whole screen instead of this one section? Open a page and copy it entire.
All of them free to read, copy and install — no account, no locked tiles, no watermarked preview. The whole catalog is open, and so are the API and the CLI.
Browse Retrieval & ContextCopying the code is free. Putting it in client work or a paid product is what Pro is for — the licence, not the access.
The RAG debugging surface: ranked passages with similarity as a meter, matched spans in real mark elements, and filter chips wired as a radiogroup so arrows move between them.
The published footnotes under an answer — ordered list, real cite and time elements, the claim each source supports, and a staleness warning written in words rather than shown as an amber dot.
Choosing what the assistant may read, with indexing state told honestly — a half-indexed source says so rather than showing a green tick — and the footer stating the effect of the selection, not its cardinality.
What is in the context and what fell out of it — a stacked budget with the reply reserve drawn as a segment, and the dropped chunks named with the reason, which is the part nobody ships.
A green tick means the connector works, not that the answers are current. Freshness as an age in words per source, the headline taken from the stalest one, and a failed sync that still says what age it is answering from.
Retrieved sources ranked by how stale they are, because a confident answer from a two-year-old document is the failure people do not catch.
Which sources this answer may draw on, shown as a scope the user can read before asking rather than a citation list after.
How an answer is tied to its sources, and what the system does when it cannot find any.