Skip to content
Shaken UI
Sign in

Sources

Save

The links an agent used for a reply, as a Used 5 sources toggle with stacked favicons that opens into a numbered list of titles and domains.

Category
AI elements
Version
0.1.0
Frameworks
Next.js, Vite + React
Styling
Tailwind CSS v4

Preview

Sources preview

Put PgBouncer in transaction mode in front of the database and cap each function at one connection. Serverless functions open a new connection per cold start, so without a pooler a traffic spike exhausts the 100 connection limit within seconds.

Installation

npx @shakenui/cli add sources

Review the plan first. A dry run lists every file and package without changing anything:

npx @shakenui/cli add sources --dry-run

Usage

sources-example.tsx
import { Sources } from "@/components/shaken/agent/sources";

const sources = [
  { title: "Connection pooling with PgBouncer", url: "https://www.pgbouncer.org/features.html" },
  { title: "Tuning max_connections for small instances", url: "https://www.postgresql.org/docs/current/runtime-config-connection.html" },
  { title: "Serverless Postgres and connection limits", url: "https://neon.tech/docs/connect/connection-pooling" },
  { title: "Prisma: connection management in serverless functions", url: "https://www.prisma.io/docs/guides/performance-and-optimization/connection-management" },
  { title: "Why transaction pooling breaks prepared statements", url: "https://github.com/pgbouncer/pgbouncer/issues/695" },
];

export default function SourcesExample() {
  return (
    <div className="grid w-full max-w-lg gap-3">
      <p className="text-sm leading-relaxed text-zinc-800 dark:text-zinc-200">
        Put PgBouncer in transaction mode in front of the database and cap each function at one connection. Serverless
        functions open a new connection per cold start, so without a pooler a traffic spike exhausts the 100 connection limit
        within seconds.
      </p>
      <Sources sources={sources} defaultOpen />
    </div>
  );
}

API

PropTypeDefaultDescription
sources{ title, url, domain?, icon? }[]—Sources in citation order. domain defaults to the URL host; icon is a favicon URL with the domain initial as fallback.
searchingbooleanfalseThe agent is still collecting: the toggle shows the Searching mark and the count so far.
labelReactNode—Replaces the toggle text.
previewCountnumber3How many favicons stack in the toggle.
defaultOpen / open / onOpenChangeboolean / (open) => void—Base UI Collapsible open state, uncontrolled or controlled.

Accessibility

  • Built on Base UI Collapsible: the toggle is a button with aria-expanded and aria-controls, operable with Enter and Space.
  • Each source is a real link with a visible focus ring and an sr-only note that it opens in a new tab.
  • Favicons are decorative (aria-hidden); the title and domain name each source.
  • The list height and opacity animate in 220ms and close in 180ms; instant with reduced motion. The Searching mark holds a still frame under reduced motion.

Files

Installed into src/components/shaken, or components/shaken when the project has no src directory.

  • src/components/shaken/agent/sources.tsxsources
  • Also installs agent-state@0.1.0registry dependency
  • npm packages: @base-ui/react@^1.9.0React and Tailwind CSS v4 required

Source

The exact source the CLI installs, from /r/items/react/sources/0.1.0.json.

agent/sources.tsxShow
agent/sources.tsx
"use client";

import { Avatar } from "@base-ui/react/avatar";
import { Collapsible } from "@base-ui/react/collapsible";
import type { ReactNode } from "react";
import { AgentState } from "./agent-state";

function cx(...classes: (string | false | null | undefined)[]) {
  return classes.filter(Boolean).join(" ");
}

const ease = "ease-[cubic-bezier(0.23,1,0.32,1)]";

export interface SourceItem {
  /** Page title. */
  title: string;
  /** Full URL the agent read. */
  url: string;
  /** Shown under the title. Defaults to the URL's host without `www.`. */
  domain?: string;
  /** Favicon image. Falls back to the domain's initial while loading or when it fails. */
  icon?: string;
}

export interface SourcesProps extends Omit<Collapsible.Root.Props, "className" | "children"> {
  sources: SourceItem[];
  /** Replaces the toggle text. Defaults to "Used 5 sources". */
  label?: ReactNode;
  /** The agent is still collecting sources: the toggle shows a Searching mark and the count so far. */
  searching?: boolean;
  /** How many favicons stack in the toggle. */
  previewCount?: number;
  className?: string;
}

/** Host of a URL without `www.`, or the URL itself when it does not parse. */
export function sourceDomain(url: string): string {
  try {
    return new URL(url).hostname.replace(/^www\./, "");
  } catch {
    return url;
  }
}

/**
 * The links an agent used for a reply: a quiet "Used 5 sources" toggle with stacked favicons that
 * opens into a numbered list of titles and domains. Numbers match Inline Citation chips.
 */
export function Sources({ sources, label, searching = false, previewCount = 3, className, ...props }: SourcesProps) {
  const count = sources.length;
  const noun = count === 1 ? "source" : "sources";
  const text = label ?? (searching ? `Searching, ${count} ${noun} so far` : `Used ${count} ${noun}`);

  return (
    <Collapsible.Root className={cx("w-full", className)} {...props} disabled={props.disabled || count === 0}>
      <Collapsible.Trigger
        className={cx(
          "group -ml-1.5 inline-flex min-h-8 max-w-[calc(100%+0.375rem)] cursor-pointer items-center gap-2 rounded-lg py-1 pr-2 pl-1.5 text-left text-sm",
          "text-zinc-600 transition-[background-color,color] duration-150 ease-out motion-reduce:transition-none",
          "hover:bg-zinc-950/[0.04] hover:text-zinc-950 data-panel-open:text-zinc-950",
          "dark:text-zinc-400 dark:hover:bg-white/[0.06] dark:hover:text-white dark:data-panel-open:text-white",
          "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-sky-500",
          "data-disabled:cursor-default data-disabled:hover:bg-transparent",
        )}
      >
        {count > 0 ? (
          <span aria-hidden="true" className="flex shrink-0 items-center">
            {sources.slice(0, previewCount).map((source, index) => (
              <SourceIcon
                key={source.url}
                source={source}
                className={cx(
                  "ring-2 ring-white dark:ring-black",
                  index > 0 && "-ml-1.5",
                  `transition-[opacity,scale] duration-200 ${ease} starting:scale-90 starting:opacity-0 motion-reduce:transition-none`,
                )}
              />
            ))}
          </span>
        ) : null}
        {searching ? (
          <AgentState variant="plain" size="sm" activity="searching" label={text} className="text-sm" />
        ) : (
          <span className="min-w-0 truncate font-medium">{text}</span>
        )}
        <svg
          aria-hidden="true"
          viewBox="0 0 16 16"
          fill="none"
          className={cx(
            "size-4 shrink-0 text-zinc-400 dark:text-zinc-500",
            `transition-[rotate,color] duration-200 ${ease} motion-reduce:transition-none`,
            "group-hover:text-current group-data-panel-open:rotate-180 group-data-panel-open:text-current",
            count === 0 && "hidden",
          )}
        >
          <path d="m4.5 6.25 3.5 3.5 3.5-3.5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
        </svg>
      </Collapsible.Trigger>
      <Collapsible.Panel
        className={cx(
          "h-(--collapsible-panel-height) overflow-hidden",
          `transition-[height,opacity] duration-220 ${ease} motion-reduce:transition-none`,
          "data-starting-style:h-0 data-starting-style:opacity-0",
          "data-ending-style:h-0 data-ending-style:opacity-0 data-ending-style:duration-180",
        )}
      >
        <ol className="mt-1.5 grid gap-px">
          {sources.map((source, index) => (
            <li key={source.url}>
              <a
                href={source.url}
                target="_blank"
                rel="noreferrer"
                className={cx(
                  "group/link -mx-1.5 grid grid-cols-[1.25rem_1.25rem_minmax(0,1fr)] items-center gap-x-2.5 rounded-lg px-1.5 py-1.5",
                  "transition-colors duration-150 ease-out motion-reduce:transition-none",
                  "hover:bg-zinc-950/[0.04] dark:hover:bg-white/[0.06]",
                  "focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-sky-500",
                )}
              >
                <span className="text-right font-mono text-xs text-zinc-500 tabular-nums">{index + 1}</span>
                <SourceIcon source={source} />
                <span className="min-w-0">
                  <span className="block truncate text-sm leading-5 text-zinc-950 group-hover/link:underline group-hover/link:decoration-zinc-950/30 group-hover/link:underline-offset-2 dark:text-white dark:group-hover/link:decoration-white/40">
                    {source.title}
                  </span>
                  <span className="block truncate text-xs leading-4 text-zinc-500">{source.domain ?? sourceDomain(source.url)}</span>
                </span>
                <span className="sr-only">(opens in a new tab)</span>
              </a>
            </li>
          ))}
        </ol>
      </Collapsible.Panel>
    </Collapsible.Root>
  );
}

/** A 20px round favicon with the domain's initial as its fallback. Decorative; the title names the source. */
export function SourceIcon({ source, className }: { source: SourceItem; className?: string }) {
  const domain = source.domain ?? sourceDomain(source.url);
  return (
    <Avatar.Root
      aria-hidden="true"
      className={cx(
        "relative inline-flex size-5 shrink-0 items-center justify-center overflow-hidden rounded-full bg-white select-none",
        "shadow-[inset_0_0_0_1px_rgb(9_9_11/0.1)] dark:bg-black dark:shadow-[inset_0_0_0_1px_rgb(255_255_255/0.16)]",
        className,
      )}
    >
      {source.icon ? <Avatar.Image src={source.icon} alt="" className="size-3.5 object-contain" /> : null}
      <Avatar.Fallback className="text-[10px] leading-none font-semibold text-zinc-600 dark:text-zinc-300">
        {domain.charAt(0).toUpperCase()}
      </Avatar.Fallback>
    </Avatar.Root>
  );
}