Quick Start

Wire Cascade into your app in under five minutes. Your docs double as the demo as you onboard users.

1. Wrap your app

Add HoverKitProvider near the root. Provide at least one source—here we show the markdown source for a knowledge web stored on disk.

import { HoverKitProvider } from 'cascade-cards';
import { markdownSource } from 'cascade-cards-source-markdown';

const wikiSource = markdownSource({ glob: 'content/wiki/**/*.md' });

export function AppProviders({ children }: { children: React.ReactNode }) {
  return (
    <HoverKitProvider
      sources={[wikiSource]}
      behavior={{ pinOnHoverDelayMs: 600 }}
    >
      {children}
    </HoverKitProvider>
  );
}

2. Tag your terms

Wrap any copy with <HoverTerm term="...">. Cascade will resolve the term through the sources you configured.

import { HoverTerm } from 'cascade-cards';

export function EmptyStatesDoc() {
  return (
    <p>
      Onboarding is smoother when you provide <HoverTerm term="hover knowledge">hover knowledge</HoverTerm>
      so users explore context without leaving the screen.
    </p>
  );
}

Hover the highlighted terms across these docs to see the cards in action.

3. Inline Data Source (Easiest)

For client-side apps or simple use cases, create an inline data source:

import type { DataSource, DataSourceContent } from "cascade-cards-core";

const myContent: Record<string, DataSourceContent> = {
  "saas": {
    title: "SaaS",
    markdown: "Software as a Service - cloud-based software delivery.",
    links: [{ term: "cloud" }]
  },
  "api": {
    title: "API",
    markdown: "Application Programming Interface...",
  }
};

const inlineSource: DataSource = {
  name: 'inline',
  async resolve(term: string) {
    return myContent[term.toLowerCase()] ?? null;
  }
};

Perfect for Next.js App Router client components!

4. Extend with REST

Pull live content from your API using the REST helper:

import { restSource } from 'cascade-cards-source-rest';

const restDocs = restSource({
  baseUrl: 'https://api.cascade.cards',
  termPath: (term) => `/docs/${term}`,
  transform: (payload) => payload?.content ?? null,
});

Combine multiple sources—Cascade will try each one until it finds a match.

Complete Next.js Example

Here's a full working example for Next.js App Router:

// app/layout.tsx
import "cascade-cards/styles.css";
import { HoverKitWrapper } from "@/components/HoverKitWrapper";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <HoverKitWrapper>
          {children}
        </HoverKitWrapper>
      </body>
    </html>
  );
}

// app/page.tsx
import { HoverTerm } from "cascade-cards";

export default function HomePage() {
  return (
    <p>
      Learn about <HoverTerm term="saas">SaaS</HoverTerm> and 
      <HoverTerm term="api">APIs</HoverTerm>.
    </p>
  );
}