Installation

Socratic UI components are distributed as a shadcn custom registry. Source files are copied into your project — no npm package to install.

1. Add the registry

Open your project's components.json and add the Socratic registry:

// components.json
{
  "registries": {
    "@socratic": "https://socraticui.com/r/{name}.json"
  }
}

2. Install components

Install the components you need. Each one is self-contained — install as many or as few as your project requires.

npx shadcn add @socratic/single-select

You can install multiple at once:

npx shadcn add @socratic/single-select @socratic/multi-select @socratic/priority-rank

This copies source files into components/socratic-ui/ and auto-installs any npm dependencies (clsx, tailwind-merge, zod, motion) and shadcn primitives (card, button, etc.) that the components need.

3. Wire up with the AI SDK

Every component has a matching Zod schema pair in components/socratic-ui/schemas.ts. Use the question schema as a tool's parameters so the model can call it:

import { tool } from "ai";
import {
  singleSelectQuestionSchema,
  singleSelectResponseSchema,
} from "@/components/socratic-ui/schemas";

const tools = {
  askSingleSelect: tool({
    description: "Ask the user to pick one option from a list",
    parameters: singleSelectQuestionSchema,
  }),
};

4. Render in your chat UI

When the model invokes the tool, render the matching component and feed the user's answer back via addToolResult:

import { SingleSelect } from "@/components/socratic-ui/single-select";

// Inside your chat message renderer, when the tool call matches:
<SingleSelect
  question={toolCall.args.question}
  options={toolCall.args.options}
  value={selected}
  onChange={(value) => {
    setSelected(value);
    addToolResult({
      toolCallId: toolCall.toolCallId,
      result: { selected: value },
    });
  }}
/>

The response schema ( singleSelectResponseSchema) documents the shape the model receives back. Every component follows the same pattern: question schema in, response schema out.

All components

To install every Socratic UI component at once:

npx shadcn add \
  @socratic/single-select \
  @socratic/multi-select \
  @socratic/priority-rank \
  @socratic/fill-blank \
  @socratic/negation-select \
  @socratic/open-questions \
  @socratic/spectrum \
  @socratic/agreement-spectrum \
  @socratic/card-sort \
  @socratic/spatial-canvas \
  @socratic/quick-estimate \
  @socratic/conditional-branch \
  @socratic/matrix \
  @socratic/goals-non-goals \
  @socratic/user-story-builder \
  @socratic/metric-target \
  @socratic/question-sequence