Fill in the Blank

Preview

Design guidance

Use typed blanks for open answers and a choice bank for a finite set. Give each slot an accessible label. The sentence supplies visible context; empty answers can remain text-free.

Choice values identify consumable answers. A selected choice stays visible and disabled in the bank. Click or tap another choice to replace it. Focus a blank and press its option key to assign, or Delete/Backspace to clear. Drag a choice onto an eligible blank to assign it directly. Keyboard dragging uses Enter to start, Tab between eligible targets, Enter to drop and Escape to cancel.

Keep the answer key and checking action in your application. Supply status only after checking, and clear it when an answer changes. Put the checking action inside FillInTheBlank; result feedback and explicitly revealed hints follow it.

Installation

npx shadcn@latest add https://ghost-ui.com/r/fill-in-the-blank.json

Basic usage

12345678910111213import { FillInTheBlank, type FillInTheBlankPart } from "@/components/ui/fill-in-the-blank";

const parts: FillInTheBlankPart[] = [
  { type: "text", text: "An acceptance criterion links a user" },
  { type: "slot", id: "action", kind: "typed", label: "Action" },
  { type: "text", text: "to an observable" },
  { type: "slot", id: "outcome", kind: "typed", label: "Outcome" },
  { type: "text", text: "." },
];

export default function TypedBlanksDemo() {
  return <FillInTheBlank parts={parts} defaultValues={{ action: "action" }} aria-label="Complete the acceptance criterion" />;
}

Structures

parts contains text and stable, named slots. Typed answers compose Input. Choice answers compose a read-only Input and Button bank, or Select for the popup presentation. A hidden native select keeps bank answers available to form submission and required validation. The bank follows the focused choice slot.

children holds caller-owned actions below the sentence and bank. Feedback follows the actions. Dragging uses one internal behavior owner shared with RankingField; assignment and grading stay with their respective owners.

Examples

Typed blanks

Use open text when the answer cannot be represented by a fixed choice list. Inputs use the shared default control height. Answer text stays centered. Boxes start at 100px, grow with their text, and stay within the sentence width. Empty boxes are dashed; filled boxes are solid.

Choice answer bank

Keep finite choices visible below the sentence. Choices have dotted borders and can be clicked, selected by key, or dragged into the answer box.

Multiple choice targets

Focus either blank to choose its answer. The same option value can be used once across the sentence. Replacing or clearing an answer makes its old choice available again.

Underline typed answers

Use variant="underline" to give answers only a bottom boundary. The line stays thin: subtle at rest, darker on hover, and the theme accent on focus. Hover and focus add no background fill. Checked states use their result color.

Underline choices

The same variant applies to the answer box and bank. Empty answer lines are dashed; choice lines are dotted.

Horizontal wrap

The default choiceLayout="wrap" moves choices onto another line when space runs out.

Vertical choices

Use choiceLayout="vertical" for a list of choices.

Horizontal scroll

Use choiceLayout="scroll" to keep choices in one bounded row. Keyboard focus brings each choice into view.

Select presentation

Use a popup when choices need less space. The values and single-use rule stay the same; dragging applies to the bank presentation.

Optional answer checking

The caller supplies the button and evaluates the answers. Basic use has no checking action.

Correct answer

Apply status="correct" to checked answers. Editing clears the caller's result.

Incorrect answer

Apply status="incorrect" to the wrong answer. This example gives feedback without revealing the answer key.

Incorrect answer with a hint

Set a slot's hint and showHint when your application chooses to reveal help. The hint appears below Check answer and stays associated with its input.

Required answers

Named values participate in native forms. Required empty answers prevent submission.

Disabled answers

Use disabled to preserve a visible answer while preventing changes.

Shared dragging behavior

RankingField uses the same drag transport for reordering. Its move controls remain available as an alternative.

API reference

Text parts use type="text" and text. Slots use type="slot", id, kind="typed" | "choice", and label. Optional slot properties are placeholder, disabled, required, status="correct" | "incorrect", hint, and showHint (false by default).

Choice slots accept options with non-empty unique value, label, optional keyboard key, and optional disabled. The same value across choice slots identifies the same single-use answer. Keys default to A–Z for the first 26 choices; use explicit single-character keys for longer banks. Typed text does not consume choices. Caller-supplied values are preserved; pass valid choice values and avoid duplicate controlled assignments.

Native div attributes, className, children and the div ref are forwarded. Bank shortcuts apply only to a focused read-only answer control and ignore modified or composing keys. No answer key, automatic grading or hint reveal is built in.