# Question builder

A React block (a whole screen) in [Beamline](https://beamline.io/)'s [Education](https://beamline.io/components/apps/education) app. Live demo: https://beamline.io/components/question-builder

Questions built beside their material. A reading passage (imported, with an import pending or failed said with Try again, or pasted) whose words become answer options: select words, or type them, and add them as a right or a wrong answer; overlapping options are refused in words; editing the text keeps every option before and after the edit on its words and marks one the edit cut through; replacing the passage marks the questions written for the old version until each is confirmed to still fit, and publishing waits until nothing needs a look. A labelled picture whose places are fractions of it (so they hold at any width): suggested places are checked one by one, any place moves by drag or by arrow keys, wrong labels are added; the image loading and unavailable are their own states. The learner preview of each: options numbered in the text, chosen and checked, each one right, not an answer or missed; labels picked and put at places by press or key, every place marked right or wrong. An answer option's colour says what it is: right in green, a wrong one (a distractor) in quiet ink, its number tying the words in the passage to the list. Typing the exact words and adding a question open on demand; an option's delete shows on the row pointed at.

## Use it for

- Teachers writing questions on a reading passage or a picture, checking them as a learner would, and publishing the set.
- Any question authoring tied to source material (training checks on a policy, product knowledge quizzes, anatomy or parts diagrams).

## Not for

- Grading the answers ([grading-desk](https://beamline.io/components/grading-desk)).
- A course's lessons and schedule ([course-builder](https://beamline.io/components/course-builder)).
- A general form builder.

## Anatomy

- head: Reading passage / Labelled picture, Author / Learner preview, Draft or Published, Publish; what blocks publishing said under it
- passage (author): title and version; the text with options marked and numbered (a right one underlined in full ink); the offer bar: the selected words with Add as a right answer, Add as a wrong answer, Cancel, or Find the exact words; Answer options: number, words (or that they were lost), right or wrong (pressing it switches), Remove; Edit the text and Replace the passage
- questions: number, prompt, what the option question asks, Written for version N with Still fits, Remove; Add a question
- passage (learner): the prompt, the text with numbered options as toggles, Check my answer, the result line and Try again
- picture (author): the picture with numbered places (dashed while suggested), the places' list with Accept or Checked, wrong labels as chips with Remove, Add a wrong label, Save labels
- picture (learner): the picture with numbered drop places, the label pool, empty places counted, Check my answer, the results list

## States

- no options
- words selected awaiting an option
- valid option set
- overlap refused
- words not found
- text edit keeps options
- text edit invalidates an option
- passage replaced: questions need a look
- publishing blocked
- publishing
- published
- import pending
- import failed
- pasted passage
- learner selection
- submitted per-option feedback
- image loading
- image unavailable
- suggested places unchecked
- place moved by hand
- wrong label added
- saving
- save refused
- learner incomplete
- submitted per-place correctness

## Keyboard

- Tab through the head, the passage's offer bar (type words, Find, then Add as a right or wrong answer) and each option's switch and Remove
- a place on the picture: arrow keys move it by 1% (Shift: 5%); its name says where it is
- learner: a numbered option toggles with Enter or Space; a label in the pool picks with Enter, then Enter on a place puts it there (Enter on a filled place takes it back)

## Motion

Option toggles and places change at once; a dragged place follows the pointer and goes back on Escape. Nothing moves at rest.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `QuestionSet` | — | The set as saved; edits are reported through onChange and held by the app. |
| `defaultValue` | `QuestionSet` | — | Initial selection when uncontrolled; omitted by default. |
| `onValueChange` | `((set: QuestionSet) => void)` | — | Reports the selected value after a change; no callback by default. |
| `importing` | `PassageImport \| null` | — | A document being imported, or one that failed; null when none. |
| `onRetryImport` | `(() => void)` | — |  |
| `onSaveLabels` | `((q: LabelQuestion) => void \| Promise<unknown>)` | — | Saves the labelled picture; reject with why to keep the changes. |
| `published` | `boolean` | — | Whether learners have this set. |
| `onPublish` | `(() => void \| Promise<unknown>)` | — | Publishes; refused on screen while a question needs a look or an option lost its words. Reject with why. |
| `tab` | `"passage" \| "picture"` | — |  |
| `defaultTab` | `"passage" \| "picture"` | — |  |
| `onTabChange` | `((tab: "picture" \| "passage") => void)` | — |  |
| `mode` | `"author" \| "learner"` | — |  |
| `defaultMode` | `"author" \| "learner"` | — |  |
| `onModeChange` | `((mode: "author" \| "learner") => void)` | — |  |
| `className` | `string` | — | Classes on the documented visual root; no override by default. |
| `style` | `CSSProperties` | — | Inline styles on the documented visual root; no overrides by default. |
| `ref` | `Ref<HTMLDivElement>` | — | Receives the documented native target or imperative handle; omitted by default. |

## Built from

- tabs
- [segmented-control](https://beamline.io/components/segmented-control)
- textarea
- input
- progress
- badge
- button
- alert
- [empty-state](https://beamline.io/components/empty-state)
- skeleton

## Dependencies

`lucide-react`

## Import

```tsx
import { QuestionBuilder } from "@beamline/question-builder";
```

## Get it

Question builder is part of Beamline UI. Install the parts you need in your React app as compiled packages or editable source. [Get Beamline](https://beamline.io/checkout?pack=complete) · [Connect your agent](https://beamline.io/connect)

## More in Education

- [Course builder](https://beamline.io/components/course-builder): Setting a course up. The learning path as ordered sets, each with its release rule in place (at once, a delay after the set before drawn as a bar you…
- [Program modules](https://beamline.io/components/program-modules): A wellness or coaching program's modules as a practitioner builds them. The modules down the side with where each stands (draft, published at a revision…
- [Grading desk](https://beamline.io/components/grading-desk): Grading a quiz or an assignment. The submissions down the side, not graded first, the open one beside its grade. A quiz attempt shows each question's…
- [Course dashboard](https://beamline.io/components/course-dashboard): A course's staff view: its identity (draft or published, who may join, how it runs, its lessons) with Publish through your app, Preview as a learner and…
- [Course home](https://beamline.io/components/course-home): A learner's course, week by week, in the cohort's time zone: each lesson done or not, a project's draft or submission, a reflection answered or not, a…
- [Volunteer rota](https://beamline.io/components/volunteer-rota): Several plans side by side for the people who staff them: plans as columns, teams and their positions as rows, each cell the people scheduled with their…
- [Gift desk](https://beamline.io/components/gift-desk): A gift or tickets taken in person, on a phone at an event or at a desk: the gift entered large in its currency, once or monthly (monthly said as an…
- [Gift batches](https://beamline.io/components/gift-batches): Gift batches between counting and the books: batches a counting team enters, each with the day the gifts were received (apart from when they were entered…

Part of [Beamline UI: polished, editable React components and complete screens for custom applications](https://beamline.io/). [Build your own style from any look; tokens, fonts, radii, motion; not only colours](https://beamline.io/docs/customize).