Runtime block catalog (v3 default)¶

H5P equivalents

Many LessonKit blocks mirror H5P content types as native React components (not embedded H5P; no .h5p import). Quiz = H5P Multiple Choice; Tier B P0 question types ship in Catalog v2 (framework 1.1.0). Full mapping: H5P capability map · guide: Coming from H5P?.

The block catalog describes every framework-owned learning primitive in @lessonkit/react. Use it to validate generated code, document supported props, and align AI/codegen workflows with the same runtime components authors use today.

H5P names for v1 blocks¶

LessonKit block	H5P display name	H5P machine name (typical)
`Quiz` / `KnowledgeCheck`	Multiple Choice	`H5P.MultiChoice`
`Scenario`	(scenario / content area)	—
`Reflection`	(open text / reflection)	—
`Course` / `Lesson`	(course structure)	—
`ProgressTracker`	(progress UI)	—

Catalog artifacts¶

Artifact	Path
Version	`blockCatalogV3Version = 3` (default for `buildBlockCatalog()`; legacy v1 export: `blockCatalogVersion = 1`)
JSON	`@lessonkit/react/block-catalog.v3.json` (must match `buildBlockCatalog()` in tests)
JSON Schema	`@lessonkit/react/block-contract.v3.json`
Programmatic API	`buildBlockCatalog()`, `getBlockCatalogEntry(type)`, `BLOCK_CATALOG`

Import in Node or bundlers:

import catalog from "@lessonkit/react/block-catalog.v1.json" assert { type: "json" };
// catalog.schemaVersion === 1
// catalog.entries — one object per block type

Block types (v1)¶

Type	Category	Required IDs	Telemetry
`Course`	container	`courseId`	`course_started`, `course_completed`
`Lesson`	container	`lessonId`	`lesson_started`, `lesson_completed`, `lesson_time_on_task`
`Scenario`	content	optional `blockId`	manual `interaction` via `useTracking()`
`Reflection`	content	optional `blockId`	manual `interaction` via `useTracking()`
`Quiz`	assessment	`checkId`	`quiz_answered`, `quiz_completed`
`KnowledgeCheck`	assessment	(alias of `Quiz`)	same as `Quiz`
`ProgressTracker`	chrome	—	none

Composition rules¶

ThemeProvider
  └── Course (courseId)
        ├── ProgressTracker
        └── Lesson (lessonId)
              ├── Scenario (blockId?)
              ├── Reflection (blockId?)
              ├── Quiz / KnowledgeCheck (checkId)
              └── custom UI + useTracking()

Quiz / KnowledgeCheck must be inside an active Lesson for quiz telemetry (lessonId required).
Scenario / Reflection: set blockId when you want block-level URNs on interaction events (see Telemetry reference).
ProgressTracker reads runtime progress; place inside Course.

Per-block contracts¶

Course¶

Prop	Type	Required	Description
`title`	string	yes	Course title (h1)
`courseId`	CourseId	yes	Stable course id
`config`	LessonkitConfig (minus courseId)	no	Tracking, xAPI, session
`children`	ReactNode	yes	Lessons and chrome

A11y: <section aria-label={title}>, <h1>.
Theming: Inherits --lk-* from ThemeProvider.
Telemetry: Provider emits course_started on mount; completeCourse() emits course_completed.

Lesson¶

Prop	Type	Required	Description
`title`	string	yes	Lesson title (h2)
`lessonId`	LessonId	yes	Stable lesson id
`children`	ReactNode	yes	Blocks and content

A11y: <article aria-label={title}>, <h2>.
Theming: Inherits global tokens.
Telemetry: lesson_started on mount; lesson_completed + lesson_time_on_task on unmount or lesson switch.

Scenario¶

Prop	Type	Required	Description
`blockId`	BlockId	no	Block URN segment for interactions
`children`	ReactNode	yes	Narrative and custom UI

A11y: <section aria-label="Scenario">.
Theming: data-lk-block-id when blockId set.
Telemetry: No automatic events; use useTracking().track("interaction", …).

Reflection¶

Prop	Type	Required	Description
`blockId`	BlockId	no	Block URN segment
`prompt`	string	no	Question above textarea
`children`	ReactNode	no	Optional content above textarea

A11y: <section aria-label="Reflection">; textarea uses aria-labelledby or aria-label.
Theming: data-lk-block-id when blockId set.
Telemetry: Manual interaction events (e.g. on submit).

Quiz / KnowledgeCheck¶

Prop	Type	Required	Description
`checkId`	CheckId	yes	Assessment id (sync with `lessonkit.json`)
`question`	string	yes	Question text
`choices`	string[]	yes	Radio options
`answer`	string	yes	Correct choice (must match one option)

A11y: Fieldset + radios; role="status" aria-live="polite" for feedback; visually hidden legend.
Theming: data-lk-check-id from checkId.
Telemetry: quiz_answered on each choice; quiz_completed on first correct answer.

ProgressTracker¶

No props.

A11y: <aside aria-label="Progress">.
Theming: Inherits global tokens.
Telemetry: None (display-only).

Catalog v2 (framework 1.1.0 — shipped)¶

H5P question types (1.1.0)

These LessonKit blocks are React implementations of common H5P question content types. Each implements the shared Assessment contract (scores, retry, solutions, xAPI)—see SPEC.md.

blockCatalogVersion = 2 adds H5P-aligned assessments under a shared Assessment contract. Full traceability: H5P capability map.

LessonKit block	H5P display name
`TrueFalse`	True/False
`FillInTheBlanks`	Fill in the Blanks
`DragAndDrop`	Drag and Drop
`DragTheWords`	Drag the Words
`MarkTheWords`	Mark the Words
`AssessmentSequence`	Question Set

Block	Category	`checkId`	1.1.x tranche
`TrueFalse`	assessment	required	P0
`FillInTheBlanks`	assessment	required	P0
`DragAndDrop`	assessment	required	P0
`DragTheWords`	assessment	required	P0
`MarkTheWords`	assessment	required	P0
`AssessmentSequence`	container	per child	P0
`Quiz` / `KnowledgeCheck`	assessment	required	existing (contract alignment)

Shipped block criteria: catalog JSON entry, unit tests, telemetry mapping, export parity where applicable. Storybook coverage is expanding—see the Component gallery.

Import @lessonkit/react/block-catalog.v2.json or buildBlockCatalog({ version: 2 }). Use { version: 1 } for legacy generators.

Catalog v3 (framework 1.2.0 — shipped)¶

Default in 1.2.0: buildBlockCatalog() and buildBlockCatalog({ version: 3 }).

Adds content primitives (Text, Heading, Image), compound containers (Page, InteractiveBook), Tier C/D blocks (Accordion, DialogCards, Flashcards, ImageHotspots, ImageSlider, FindHotspot, FindMultipleHotspots), and allowedChildTypes / compoundContract on compound entries.

Block	H5P display name (typical)
`Page`	Column / page (Interactive Book chapter)
`InteractiveBook`	Interactive Book
`Accordion`	Accordion
`DialogCards`	Dialog Cards
`Flashcards`	Flashcards
`ImageHotspots`	Image Hotspots
`ImageSlider`	Image Slider
`FindHotspot`	Find the Hotspot
`FindMultipleHotspots`	Find Multiple Hotspots

Catalog v3 additions (framework 1.3.0)¶

Block	H5P display name	Notes
`Slide`	Course Presentation (slide row)	`compoundContract`; per-slide allowlist (no `ProgressTracker`)
`SlideDeck`	Course Presentation	`Slide[]` children; `slide_viewed` telemetry; keyboard nav

SlideDeck props: blockId (required), title, showDeckScore, Slide children. Implements CompoundHandle with session resume (persistCompoundState default true).

Catalog v3 additions (framework 1.4.0)¶

Block	H5P display name	Notes
`Video`	—	Self-hosted `<video>` primitive; nestable in `Page` / `Slide`
`TimedCue`	Interactive Video (cue)	Single child at `atSeconds`; used inside `InteractiveVideo`
`InteractiveVideo`	Interactive Video	`TimedCue[]` children; `video_cue_reached` telemetry; session resume
`Summary`	Summary	Statement-bank construct task
`ImagePairing`	Image Pairing	Match image pairs
`ImageSequencing`	Image Sequencing	Order images
`ArithmeticQuiz`	Arithmetic Quiz	Timed math prompts
`Essay`	Essay	Open text; plugin grading via `scoreAssessment`
`Questionnaire`	Questionnaire	Unscored multi-field survey
`MemoryGame`	Memory Game	Card flip pairs
`InformationWall`	Information Wall	Searchable panel grid
`ParallaxSlideshow`	Slideshow (parallax)	Static fallback under `prefers-reduced-motion`

InteractiveVideo props: blockId (required), title, src, showVideoScore?, TimedCue children. Implements CompoundHandle with session resume (video time + cue index + child assessment state).

Slide / Page allowlist: includes Video, Summary, and all 1.4.0 content blocks above.

Import @lessonkit/react/block-catalog.v3.json or pin { version: 2 } until generators are updated.

Catalog v3 additions (framework 1.5.0)¶

Block	Role	Notes
`BranchingScenario`	Compound	Graph navigation with `BranchNode` / `BranchChoice`; persists `__lk_bs__` branch meta
`BranchNode`	Compound child	Page-like content container; `terminal` locks choices
`BranchChoice`	Navigation	Emits `branch_selected` via parent scenario
`Embed`	Content	Sandboxed iframe (`https` in production); telemetry strips credentials from `src`
`Chart`	Content	`bar` or list-style `pie` plus accessible data table; unknown types fall back to table

Chart note: type="pie" renders segment labels as a list (not geometric slices). Use bar or the table for precise comparisons.

Branching resume: Sessions without __lk_bs__ meta restart at startNodeId (legacy saves before 1.5.0).

Catalog v3 additions (framework 1.6.0)¶

Block	Role	Notes
`Table`	Content	Accessible data table with optional caption
`ImageJuxtaposition`	Content	Before/after image slider
`Timeline`	Content	Event list with focus tracking
`ImageSequence`	Content	Stepped image frames
`Collage`	Content	Multi-image layout
`AudioRecorder`	Content	Browser audio capture
`CombinationLock`	Assessment	Digit entry; `checkId` required
`QrContent`	Content	QR payload with hidden reveal
`Crossword`	Assessment	Grid fill assessment
`WordSearch`	Assessment	Letter grid word find
`AdventCalendar`	Content	Door-based reveal calendar
`GameMap`	Compound	Stage graph with `MapStage` / `MapExit` children

Import @lessonkit/react/block-catalog.v3.json or buildBlockCatalog({ version: 3 }) (default). Use { version: 1 } only for legacy generators.

Catalog v3 additions (framework 1.7.0)¶

Block	Role	Notes
`SortParagraphs`	Assessment	Reorder paragraphs; `checkId` required; SPA-only LMS shell (`kind: "sortParagraphs"`)
`GuessTheAnswer`	Assessment	Scored text guess or reveal-only (`scored={false}`); SPA-only when scored
`MultimediaChoice`	Assessment	MCQ with image/audio choices; every option needs `label` + `altText`; injectable via MCQ shell
`SingleChoiceSet`	Compound	Sequential child `Quiz` / `KnowledgeCheck`; aggregated `CompoundHandle` scoring

Quiz / KnowledgeCheck variants (1.7.0): answers (multi-select), shuffleChoices / shuffleSeed, choiceFeedback. With LXPack 0.7.0+, multi-select and shuffle inject into LMS shell quizzes; feedback text remains SPA-only.

See Migration 1.6 → 1.7.

Generated prop reference (catalog v3)¶

Full prop tables for blocks beyond the v1 manual section above (auto-generated from block-catalog.v3.json):

docs/scripts/generate-block-props-doc.mjs — do not edit –>

Generated block prop reference (catalog v3)¶

Auto-generated from @lessonkit/react/block-catalog.v3.json. Regenerate: node docs/scripts/generate-block-props-doc.mjs.

TrueFalse¶

Binary true/false question with assessment contract.

Component page: TrueFalse demo (live embed + when to use)

Storybook: TrueFalse demo

Prop	Type	Required	Description
`checkId`	CheckId	yes	Stable check id.
`question`	string	yes	Question text.
`answer`	boolean	yes	Correct answer.
`enableRetry`	boolean	no	Allow retry after completion.
`enableSolutionsButton`	boolean	no	Show solution control.
`autoCheck`	boolean	no	Check answers automatically when possible.
`passingScore`	number	no	Minimum score to pass.

Required IDs: checkId

Telemetry: assessment_answered, assessment_completed

FillInTheBlanks¶

Fill-in-the-blank text with answer markers in template.

Component page: FillInTheBlanks demo (live embed + when to use)

Prop	Type	Required	Description
`checkId`	CheckId	yes	Stable check id.
`template`	string	yes	Text with blank markers.
`blanks`	FillInBlankSpec[]	no	Explicit blank specs.
`enableRetry`	boolean	no	Allow retry after completion.
`enableSolutionsButton`	boolean	no	Show solution control.
`autoCheck`	boolean	no	Check answers automatically when possible.
`passingScore`	number	no	Minimum score to pass.

Required IDs: checkId

Telemetry: assessment_answered, assessment_completed

DragAndDrop¶

Drag items onto labeled targets.

Component page: DragAndDrop demo (live embed + when to use)

Prop	Type	Required	Description
`checkId`	CheckId	yes	Stable check id.
`items`	DragItem[]	yes	Draggable items.
`targets`	DropTarget[]	yes	Drop targets.
`enableRetry`	boolean	no	Allow retry after completion.
`enableSolutionsButton`	boolean	no	Show solution control.
`autoCheck`	boolean	no	Check answers automatically when possible.
`passingScore`	number	no	Minimum score to pass.

Required IDs: checkId

Telemetry: assessment_answered, assessment_completed

DragTheWords¶

Drag words into inline blanks.

Component page: DragTheWords demo (live embed + when to use)

Prop	Type	Required	Description
`checkId`	CheckId	yes	Stable check id.
`template`	string	yes	Sentence with blank zones.
`words`	string[]	yes	Draggable word bank.
`enableRetry`	boolean	no	Allow retry after completion.
`enableSolutionsButton`	boolean	no	Show solution control.
`autoCheck`	boolean	no	Check answers automatically when possible.
`passingScore`	number	no	Minimum score to pass.

Required IDs: checkId

Telemetry: assessment_answered, assessment_completed

MarkTheWords¶

Select correct words in a sentence.

Component page: MarkTheWords demo (live embed + when to use)

Prop	Type	Required	Description
`checkId`	CheckId	yes	Stable check id.
`text`	string	yes	Source text.
`correctWords`	string[]	yes	Words to mark.
`enableRetry`	boolean	no	Allow retry after completion.
`enableSolutionsButton`	boolean	no	Show solution control.
`autoCheck`	boolean	no	Check answers automatically when possible.
`passingScore`	number	no	Minimum score to pass.

Required IDs: checkId

Telemetry: assessment_answered, assessment_completed

AssessmentSequence¶

Ordered sequence of contract-compliant assessments.

Component page: AssessmentSequence demo (live embed + when to use)

Prop	Type	Required	Description
`children`	ReactNode	yes	Assessment blocks.
`sequential`	boolean	no	One question at a time.
`enableRetry`	boolean	no	Allow retry after completion.
`enableSolutionsButton`	boolean	no	Show solution control.
`autoCheck`	boolean	no	Check answers automatically when possible.

Compound: Implements session resume when config.session.persistCompoundState is true. See Core reference — compound state.

Summary¶

Construct a summary from a statement bank in correct order.

Component page: Summary demo (live embed + when to use)

Prop	Type	Required	Description
`checkId`	CheckId	yes	Stable check id.
`statements`	string[]	yes	Available statements.
`correct`	string[]	yes	Correct ordered summary.
`instructions`	string	no	Learner-facing prompt; defaults to a multi-select instruction.
`enableRetry`	boolean	no	Allow retry after completion.
`enableSolutionsButton`	boolean	no	Show solution control.
`autoCheck`	boolean	no	Check answers automatically when possible.
`passingScore`	number	no	Minimum score to pass.

Required IDs: checkId

Telemetry: assessment_answered, assessment_completed

ImagePairing¶

Match image pairs in a memory-style task.

Component page: ImagePairing demo (live embed + when to use)

Prop	Type	Required	Description
`checkId`	CheckId	yes	Stable check id.
`pairs`	ImagePair[]	yes	Image pairs to match.
`enableRetry`	boolean	no	Allow retry after completion.
`enableSolutionsButton`	boolean	no	Show solution control.
`autoCheck`	boolean	no	Check answers automatically when possible.
`passingScore`	number	no	Minimum score to pass.

Required IDs: checkId

Telemetry: assessment_answered, assessment_completed

ImageSequencing¶

Order images in the correct sequence.

Component page: ImageSequencing demo (live embed + when to use)

Prop	Type	Required	Description
`checkId`	CheckId	yes	Stable check id.
`images`	SequencingImage[]	yes	Images to order.
`correctOrder`	string[]	yes	Correct id order.
`enableRetry`	boolean	no	Allow retry after completion.
`enableSolutionsButton`	boolean	no	Show solution control.
`autoCheck`	boolean	no	Check answers automatically when possible.
`passingScore`	number	no	Minimum score to pass.

Required IDs: checkId

Telemetry: assessment_answered, assessment_completed

ArithmeticQuiz¶

Timed arithmetic problems with optional timer.

Component page: ArithmeticQuiz demo (live embed + when to use)

Prop	Type	Required	Description
`checkId`	CheckId	yes	Stable check id.
`problems`	ArithmeticProblem[]	yes	Math problems.
`timeLimitSeconds`	number	no	Optional time limit.
`enableRetry`	boolean	no	Allow retry after completion.
`enableSolutionsButton`	boolean	no	Show solution control.
`autoCheck`	boolean	no	Check answers automatically when possible.
`passingScore`	number	no	Minimum score to pass.

Required IDs: checkId

Telemetry: assessment_answered, assessment_completed

Essay¶

Open text response; manual or plugin grading.

Component page: Essay demo (live embed + when to use)

Prop	Type	Required	Description
`checkId`	CheckId	yes	Stable check id.
`question`	string	yes	Essay prompt.
`minLength`	number	no	Minimum character length.
`enableRetry`	boolean	no	Allow retry after completion.
`enableSolutionsButton`	boolean	no	Show solution control.
`autoCheck`	boolean	no	Check answers automatically when possible.
`passingScore`	number	no	Minimum score to pass.

Required IDs: checkId

Telemetry: assessment_answered, assessment_completed

SortParagraphs¶

Order paragraphs into the correct sequence.

Component page: SortParagraphs demo (live embed + when to use)

Prop	Type	Required	Description
`checkId`	CheckId	yes	Stable check id.
`paragraphs`	string[]	yes	Paragraph texts.
`correctOrder`	number[]	yes	Correct index order.
`enableRetry`	boolean	no	Allow retry after completion.
`enableSolutionsButton`	boolean	no	Show solution control.
`autoCheck`	boolean	no	Check answers automatically when possible.
`passingScore`	number	no	Minimum score to pass.

Required IDs: checkId

Telemetry: assessment_answered, assessment_completed

GuessTheAnswer¶

Reveal or score a hidden answer.

Component page: GuessTheAnswer demo (live embed + when to use)

Prop	Type	Required	Description
`checkId`	CheckId	no	Required when scored (default).
`prompt`	string	yes	Prompt text.
`answer`	string	yes	Hidden answer.
`scored`	boolean	no	Score learner guess (default true).
`enableRetry`	boolean	no	Allow retry after completion.
`enableSolutionsButton`	boolean	no	Show solution control.
`autoCheck`	boolean	no	Check answers automatically when possible.
`passingScore`	number	no	Minimum score to pass.

Telemetry: assessment_answered, assessment_completed

MultimediaChoice¶

Multiple choice with image or audio options.

Component page: MultimediaChoice demo (live embed + when to use)

Prop	Type	Required	Description
`checkId`	CheckId	yes	Stable check id.
`question`	string	yes	Question text.
`choices`	MultimediaChoiceOption[]	yes	Media choices.
`answer`	string	yes	Correct choice label.
`enableRetry`	boolean	no	Allow retry after completion.
`enableSolutionsButton`	boolean	no	Show solution control.
`autoCheck`	boolean	no	Check answers automatically when possible.
`passingScore`	number	no	Minimum score to pass.

Required IDs: checkId

Telemetry: assessment_answered, assessment_completed

SingleChoiceSet¶

Sequential MCQ slides with aggregated scoring.

Component page: SingleChoiceSet demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	no	Stable block id.
`title`	string	no	Set title.
`showSetScore`	boolean	no	Show aggregated score.
`children`	ReactNode	yes	Quiz or KnowledgeCheck steps.
`enableRetry`	boolean	no	Allow retry after completion.
`enableSolutionsButton`	boolean	no	Show solution control.
`autoCheck`	boolean	no	Check answers automatically when possible.

Text¶

Paragraph text content.

Component page: Text demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	no	Stable block id.
`children`	ReactNode	yes	Text body.

Heading¶

Heading levels 1–3.

Component page: Heading demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	no	Stable block id.
`level`	1 \| 2 \| 3	yes	Heading level.
`children`	ReactNode	yes	Heading text.

Image¶

Image with required alt text.

Component page: Image demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	no	Stable block id.
`src`	string	yes	Image URL.
`alt`	string	yes	Alt text.

Video¶

Self-hosted video with native controls and optional captions.

Component page: Video demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`src`	string	yes	Video URL.
`poster`	string	no	Poster image URL.
`captions`	string	no	WebVTT captions URL.
`title`	string	no	Accessible title.

Required IDs: blockId

Page¶

Column layout container (H5P Column / Page).

Component page: Page demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`title`	string	no	Page title.
`children`	ReactNode	yes	Page content.

Telemetry: compound_page_viewed

Compound: Implements session resume when config.session.persistCompoundState is true. See Core reference — compound state.

InteractiveBook¶

Multi-page book with chapter navigation.

Component page: InteractiveBook demo (live embed + when to use)

Storybook: InteractiveBook demo

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`title`	string	yes	Book title.
`showBookScore`	boolean	no	Show aggregate score.
`children`	Page[]	yes	Page chapters.

Required IDs: blockId

Telemetry: book_page_viewed

Compound: Implements session resume when config.session.persistCompoundState is true. See Core reference — compound state.

Slide¶

Single slide row in a SlideDeck. Supports Video, Summary, and 1.4 blocks.

Component page: Slide demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`title`	string	no	Slide title.
`children`	ReactNode	yes	Slide content.

Telemetry: compound_page_viewed

Compound: Implements session resume when config.session.persistCompoundState is true. See Core reference — compound state.

SlideDeck¶

Multi-slide presentation with keyboard navigation.

Component page: SlideDeck demo (live embed + when to use)

Storybook: SlideDeck demo

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`title`	string	yes	Deck title.
`showDeckScore`	boolean	no	Show aggregate score.
`children`	Slide[]	yes	Slides.

Required IDs: blockId

Telemetry: slide_viewed

Compound: Implements session resume when config.session.persistCompoundState is true. See Core reference — compound state.

TimedCue¶

Timed overlay cue within InteractiveVideo.

Component page: TimedCue demo (live embed + when to use)

Prop	Type	Required	Description
`atSeconds`	number	yes	Cue time in seconds.
`label`	string	no	Cue label.
`mustComplete`	boolean	no	Block seek until completed.
`children`	ReactNode	yes	Single allowed child block.

Compound: Implements session resume when config.session.persistCompoundState is true. See Core reference — compound state.

InteractiveVideo¶

Video with timed interaction overlays.

Component page: InteractiveVideo demo (live embed + when to use)

Storybook: InteractiveVideo demo

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`title`	string	yes	Video title.
`src`	string	yes	Video URL.
`poster`	string	no	Poster image.
`captions`	string	no	WebVTT captions.
`showVideoScore`	boolean	no	Show aggregate score.
`children`	TimedCue[]	yes	Timed cues.

Required IDs: blockId

Telemetry: video_cue_reached, video_segment_completed

Compound: Implements session resume when config.session.persistCompoundState is true. See Core reference — compound state.

BranchNode¶

Graph node in a BranchingScenario with content and choices.

Component page: BranchNode demo (live embed + when to use)

Prop	Type	Required	Description
`nodeId`	string	yes	Unique node id within the scenario.
`title`	string	no	Node title.
`terminal`	boolean	no	End state node.
`children`	ReactNode	yes	Content and BranchChoice controls.

Telemetry: branch_node_viewed

Compound: Implements session resume when config.session.persistCompoundState is true. See Core reference — compound state.

BranchChoice¶

Transition control linking to a target BranchNode.

Component page: BranchChoice demo (live embed + when to use)

Prop	Type	Required	Description
`label`	string	yes	Choice label.
`targetNodeId`	string	yes	Target node id.
`scoreWeight`	number	no	Optional choice score weight.
`disabled`	boolean	no	Disable choice.

Telemetry: branch_selected

Compound: Implements session resume when config.session.persistCompoundState is true. See Core reference — compound state.

BranchingScenario¶

Graph-based branching narrative with scored paths.

Component page: BranchingScenario demo (live embed + when to use)

Storybook: BranchingScenario demo

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`title`	string	yes	Scenario title.
`startNodeId`	string	yes	Entry node id.
`showPathScore`	boolean	no	Show visited-path score.
`showPathRecap`	boolean	no	Show path recap on terminal nodes.
`children`	BranchNode[]	yes	Branch nodes.

Required IDs: blockId

Telemetry: branch_node_viewed, branch_selected

Compound: Implements session resume when config.session.persistCompoundState is true. See Core reference — compound state.

Embed¶

Sandboxed iframe embed with restrictive defaults.

Component page: Embed demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`src`	string	yes	Embed URL.
`title`	string	yes	Accessible title.
`allow`	string	no	Extra sandbox allow tokens.
`aspectRatio`	string	no	CSS aspect-ratio.

Required IDs: blockId

Telemetry: interaction

Chart¶

Simple bar or pie chart with accessible data table.

Component page: Chart demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`type`	bar \| pie	yes	Chart type.
`data`	ChartDatum[]	yes	Chart data.
`title`	string	no	Chart title.

Required IDs: blockId

Telemetry: interaction

Questionnaire¶

Unscored multi-field survey.

Component page: Questionnaire demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`fields`	QuestionnaireField[]	yes	Form fields.

Required IDs: blockId

Telemetry: questionnaire_submitted

MemoryGame¶

Card flip memory matching game.

Component page: MemoryGame demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`pairs`	MemoryPair[]	yes	Card pairs.
`selfScore`	boolean	no	Optional self-score mode.

Required IDs: blockId

Telemetry: memory_card_flipped

InformationWall¶

Searchable information panels.

Component page: InformationWall demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`panels`	InformationPanel[]	yes	Content panels.

Required IDs: blockId

Telemetry: information_wall_search

ParallaxSlideshow¶

Slideshow with parallax; static fallback when reduced motion.

Component page: ParallaxSlideshow demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`slides`	ParallaxSlide[]	yes	Slides.

Required IDs: blockId

Telemetry: parallax_slide_viewed

Accordion¶

Expandable sections.

Component page: Accordion demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`sections`	AccordionSection[]	yes	Sections.

Required IDs: blockId

Telemetry: accordion_section_toggled

DialogCards¶

Flip cards with front/back text.

Component page: DialogCards demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`cards`	DialogCard[]	yes	Cards.

Required IDs: blockId

Flashcards¶

Study flashcards with optional self-score.

Component page: Flashcards demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`cards`	Flashcard[]	yes	Cards.
`selfScore`	boolean	no	Self-score mode.

Required IDs: blockId

Telemetry: flashcard_flipped

ImageHotspots¶

Image with clickable hotspot popovers.

Component page: ImageHotspots demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`src`	string	yes	Image URL.
`alt`	string	yes	Alt text.
`hotspots`	HotspotSpec[]	yes	Hotspots.

Required IDs: blockId

Telemetry: hotspot_opened

ImageSlider¶

Carousel of images.

Component page: ImageSlider demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`slides`	ImageSlide[]	yes	Slides.

Required IDs: blockId

Telemetry: image_slider_changed

FindHotspot¶

Select the correct region on an image.

Component page: FindHotspot demo (live embed + when to use)

Prop	Type	Required	Description
`checkId`	CheckId	yes	Stable check id.
`src`	string	yes	Image URL.
`alt`	string	yes	Alt text.
`targets`	HotspotTarget[]	yes	Targets.
`correctTargetId`	string	yes	Correct target id.
`enableRetry`	boolean	no	Allow retry after completion.
`enableSolutionsButton`	boolean	no	Show solution control.
`autoCheck`	boolean	no	Check answers automatically when possible.
`passingScore`	number	no	Minimum score to pass.

Required IDs: checkId

Telemetry: assessment_answered, assessment_completed

FindMultipleHotspots¶

Select all correct regions on an image.

Component page: FindMultipleHotspots demo (live embed + when to use)

Prop	Type	Required	Description
`checkId`	CheckId	yes	Stable check id.
`src`	string	yes	Image URL.
`alt`	string	yes	Alt text.
`targets`	HotspotTarget[]	yes	Targets.
`correctTargetIds`	string[]	yes	Correct target ids.
`enableRetry`	boolean	no	Allow retry after completion.
`enableSolutionsButton`	boolean	no	Show solution control.
`autoCheck`	boolean	no	Check answers automatically when possible.
`passingScore`	number	no	Minimum score to pass.

Required IDs: checkId

Telemetry: assessment_answered, assessment_completed

Table¶

Rich text table with caption.

Component page: Table demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`caption`	string	no	Table caption.
`headers`	string[]	yes	Column headers.
`rows`	string[][]	yes	Table rows.

Required IDs: blockId

ImageJuxtaposition¶

Before/after image comparison slider.

Component page: ImageJuxtaposition demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`beforeSrc`	string	yes	Before image URL.
`afterSrc`	string	yes	After image URL.
`beforeAlt`	string	yes	Before alt text.
`afterAlt`	string	yes	After alt text.

Required IDs: blockId

Telemetry: image_juxtaposition_changed

Timeline¶

Vertical timeline of events.

Component page: Timeline demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`events`	TimelineEvent[]	yes	Timeline events.

Required IDs: blockId

Telemetry: timeline_event_viewed

ImageSequence¶

Progressive image sequence blend.

Component page: ImageSequence demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`frames`	SequenceFrame[]	yes	Sequence frames.

Required IDs: blockId

Telemetry: image_sequence_changed

Collage¶

Multi-image grid collage.

Component page: Collage demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`columns`	number	no	Grid columns.
`cells`	CollageCell[]	yes	Collage cells.

Required IDs: blockId

AudioRecorder¶

Learner audio recording (client-only storage).

Component page: AudioRecorder demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`maxDurationSeconds`	number	no	Max recording length.
`consentLabel`	string	no	Consent checkbox label.

Required IDs: blockId

Telemetry: audio_recording_started, audio_recording_completed

CombinationLock¶

Enter a digit combination to unlock.

Component page: CombinationLock demo (live embed + when to use)

Prop	Type	Required	Description
`checkId`	CheckId	yes	Stable check id.
`combination`	string	yes	Correct combination.
`label`	string	no	Prompt label.
`enableRetry`	boolean	no	Allow retry after completion.
`enableSolutionsButton`	boolean	no	Show solution control.
`autoCheck`	boolean	no	Check answers automatically when possible.
`passingScore`	number	no	Minimum score to pass.

Required IDs: checkId

Telemetry: assessment_answered, assessment_completed

QrContent¶

QR code with revealable hidden content.

Component page: QrContent demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`payload`	string	yes	QR payload URL or text.
`title`	string	no	Block title.
`hiddenTitle`	string	no	Revealed title.
`hiddenBody`	string	no	Revealed body.

Required IDs: blockId

Telemetry: qr_content_revealed

Crossword¶

Crossword puzzle grid.

Component page: Crossword demo (live embed + when to use)

Prop	Type	Required	Description
`checkId`	CheckId	yes	Stable check id.
`rows`	number	yes	Grid rows.
`cols`	number	yes	Grid columns.
`entries`	CrosswordEntry[]	yes	Clues and answers.
`enableRetry`	boolean	no	Allow retry after completion.
`enableSolutionsButton`	boolean	no	Show solution control.
`autoCheck`	boolean	no	Check answers automatically when possible.
`passingScore`	number	no	Minimum score to pass.

Required IDs: checkId

Telemetry: assessment_answered, assessment_completed

WordSearch¶

Word search puzzle (page-level only; excluded from compounds).

Component page: WordSearch demo (live embed + when to use)

Prop	Type	Required	Description
`checkId`	CheckId	yes	Stable check id.
`words`	string[]	yes	Words to find.
`size`	number	no	Grid size.
`enableRetry`	boolean	no	Allow retry after completion.
`enableSolutionsButton`	boolean	no	Show solution control.
`autoCheck`	boolean	no	Check answers automatically when possible.
`passingScore`	number	no	Minimum score to pass.

Required IDs: checkId

Telemetry: assessment_answered, assessment_completed

AdventCalendar¶

Calendar with openable doors.

Component page: AdventCalendar demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`doors`	AdventDoor[]	yes	Calendar doors.
`unlockFrom`	string	no	ISO date to unlock doors.

Required IDs: blockId

Telemetry: advent_door_opened

MapStage¶

Spatial stage in a GameMap with content and exits.

Component page: MapStage demo (live embed + when to use)

Prop	Type	Required	Description
`stageId`	string	yes	Unique stage id.
`x`	number	yes	X position percent on map.
`y`	number	yes	Y position percent on map.
`label`	string	no	Stage label.
`children`	ReactNode	yes	Content and MapExit controls.

Telemetry: map_stage_viewed

MapExit¶

Transition control linking to a target MapStage.

Component page: MapExit demo (live embed + when to use)

Prop	Type	Required	Description
`label`	string	yes	Exit label.
`targetStageId`	string	yes	Target stage id.
`scoreWeight`	number	no	Optional exit score weight.

Telemetry: map_exit_selected

GameMap¶

Spatial map branching with scored stages.

Component page: GameMap demo (live embed + when to use)

Prop	Type	Required	Description
`blockId`	BlockId	yes	Stable block id.
`title`	string	yes	Map title.
`backgroundSrc`	string	yes	Background image URL.
`startStageId`	string	yes	Entry stage id.
`showMapScore`	boolean	no	Show visited-path score.
`children`	MapStage[]	yes	Map stages.

Required IDs: blockId

Telemetry: map_stage_viewed, map_exit_selected

Regenerate after catalog changes: node docs/scripts/generate-block-props-doc.mjs.

Component pages (live demos)¶

Focused Read the Docs pages render the real component, explain when to use it, and show copy-paste examples: Component pages (59 pages — full catalog coverage).

Generated prop tables below link to the matching component page when one exists. Storybook remains useful for visual state matrices.

Storybook examples¶

Visual states and props for shipped blocks live in the monorepo Storybook gallery:

Gallery: Storybook on GitHub Pages
Local: npm run storybook from the repo root (after npm run build:packages)

Story group	Blocks demonstrated
Components/Blocks	`Scenario`, `Reflection`, `KnowledgeCheck`
Components/CourseLesson	`Course`, `Lesson`, navigation
Components/Quiz	`Quiz` — unanswered, incorrect, correct
Components/TrueFalse	`TrueFalse`
Components/Compound & Tier C/D	`InteractiveBook`, `SlideDeck`, `InteractiveVideo`, `BranchingScenario`, `Embed`, `Chart`, Tier C/D blocks

For blocks without a dedicated story yet, see framework-12-showcase and components guide.

Cross-references¶

H5P mapping: H5P capability map
Identity: Identity reference — id format and URNs (@lessonkit/core/identity-contract.v1.json)
Telemetry events: Telemetry reference — event catalog (@lessonkit/core/telemetry-catalog.v3.json)
Theming: Theming reference — token catalog (@lessonkit/themes/theme-catalog.v1.json)
Accessibility: Accessibility reference

Reference example¶

examples/lxpack-golden smoke-renders core catalog blocks (Course, Lesson, Scenario, Quiz, KnowledgeCheck, Reflection, ProgressTracker) and is the packaging golden path for CI.

Generator checklist¶

Import @lessonkit/react/block-catalog.v3.json (or buildBlockCatalog({ version: 3 })) and reject unknown block types.
Validate required props and IDs per entry (requiredIds, props).
Keep courseId and every checkId in sync with lessonkit.json. For single-spa layouts, manifest lessons[].id lists LMS shell lesson(s) only; additional in-app lessonIds may exist only in React (see Identity).
Nest blocks per parentConstraints (Quiz inside Lesson, etc.).
Do not invent non-catalog blocks in framework codegen until they ship in a future runtime catalog version (see H5P capability map).
For new assessments, see catalog v2 and implement checkId before shipping.
When shipping an H5P-parity block, complete the H5P documentation checklist (capability map ✅, H5P names here, authors guide, Storybook).