Skip to Content
OrbixDocs
Block SDK · Examples

Spaced-Repetition Flashcards

Turn toggle blocks in any document into an interactive flip-card study deck with per-viewer review scheduling.

When you write study notes, onboarding guides, or technical documentation using Toggle blocks, this block turns them into an interactive flashcard deck right on the page. Each toggle heading becomes a question, and the text nested inside the toggle becomes the answer.

Try flipping and rating the cards below—each card is pulled from concepts in this SDK documentation:

1 / 6
QuestionState
How do you store per-viewer state in useOrbixState that stays editable even when a page is shared in read-only mode?
Click card to flip
Pass { scope: 'personal' } in the options object: useOrbixState(props, 'reviews', {}, { scope: 'personal' }). Personal state is isolated to each viewer and continues to accept writes when props.isReadOnly is true.
Rate recall below to schedule next review

How it works

  1. Reads toggles from the page (useOrbixDocument) — doc.read.findBlocksByType('toggle') collects every toggle block in the document, and doc.read.getChildren(toggle.id) reads the answer blocks nested inside each toggle.
  2. Saves progress per viewer (scope: 'personal') — review timestamps and intervals (Again, Hard, Good, Easy) are stored with useOrbixState(props, 'reviews', {}, { scope: 'personal' }). Because personal state is isolated per user and works in read-only mode, you can share a single page with a class or team and everyone keeps their own review schedule.

Full block code

Copy this file into Block Studio or your local project. It only needs document: ['read'] in manifest.capabilities, which is included by default.

src/FlashcardDeckBlock.tsx
import { useMemo, useState } from 'react';
import {
  defineBlock,
  useOrbixDocument,
  useOrbixState,
  type BlockRenderProps,
} from '@orbixdocs/sdk';

type Rating = 'again' | 'hard' | 'good' | 'easy';

interface CardReview {
  rating: Rating;
  intervalDays: number;
  dueAt: number;
}

type ReviewMap = Record<string, CardReview>;

interface DeckCard {
  id: string;
  question: string;
  answer: string;
}

const INTERVAL_DAYS: Record<Rating, number> = {
  again: 0,
  hard: 1,
  good: 4,
  easy: 7,
};

export default defineBlock({
  manifest: {
    id: 'acme.flashcard-deck',
    name: 'Flashcard Deck',
    version: '1.0.0',
    sdk: '^3.0.0',
    capabilities: {
      document: ['read'],
    },
  },
  component(props: BlockRenderProps) {
    const doc = useOrbixDocument();

    // Personal scope keeps each viewer's review schedule separate, even on read-only pages
    const [reviews, setReviews] = useOrbixState<ReviewMap>(
      props,
      'reviews',
      {},
      { scope: 'personal' }
    );

    const [currentIndex, setCurrentIndex] = useState(0);
    const [isFlipped, setIsFlipped] = useState(false);

    // Extract flashcards from Toggle blocks on the current page
    const cards = useMemo<DeckCard[]>(() => {
      const toggles = doc.read.findBlocksByType('toggle');
      const extracted: DeckCard[] = [];

      for (const toggle of toggles) {
        const question = (toggle.content || '').trim();
        if (!question) continue;

        const children = doc.read.getChildren(toggle.id);
        const answer = children
          .map((child) => (child.content || '').trim())
          .filter(Boolean)
          .join('\n\n');

        if (answer) {
          extracted.push({ id: toggle.id, question, answer });
        }
      }

      return extracted;
    }, [doc, doc.blocks]);

    if (cards.length === 0) {
      return (
        <div
          style={{
            padding: 20,
            borderRadius: 12,
            background: '#09090b',
            border: '1px solid rgba(255, 255, 255, 0.08)',
            color: '#a1a1aa',
            fontSize: 13,
          }}
        >
          Add a Toggle block to this page with a question as the title and the answer nested inside
          it to generate flashcards.
        </div>
      );
    }

    const safeIndex = currentIndex % cards.length;
    const activeCard = cards[safeIndex];
    const lastReview = reviews[activeCard.id];

    const rateCard = (rating: Rating) => {
      const days = INTERVAL_DAYS[rating];
      const dueAt = Date.now() + days * 86_400_000;

      setReviews((prev) => ({
        ...prev,
        [activeCard.id]: { rating, intervalDays: days, dueAt },
      }));

      setIsFlipped(false);
      setCurrentIndex((prev) => (prev + 1) % cards.length);
    };

    return (
      <div
        style={{
          padding: 20,
          borderRadius: 12,
          background: '#09090b',
          border: '1px solid rgba(255, 255, 255, 0.08)',
          color: '#f4f4f5',
        }}
      >
        <div
          style={{
            display: 'flex',
            justifyContent: 'space-between',
            alignItems: 'center',
            marginBottom: 12,
            fontSize: 12,
            color: '#a1a1aa',
          }}
        >
          <span>
            Card {safeIndex + 1} of {cards.length}
          </span>
          {lastReview && <span>Last rated: {lastReview.rating}</span>}
        </div>

        <div
          role="button"
          tabIndex={0}
          onClick={() => setIsFlipped((v) => !v)}
          onKeyDown={(e) => {
            if (e.key === ' ' || e.key === 'Enter') {
              e.preventDefault();
              setIsFlipped((v) => !v);
            }
          }}
          style={{
            minHeight: 180,
            padding: 24,
            borderRadius: 10,
            background: '#0e0e11',
            border: '1px solid rgba(255, 255, 255, 0.09)',
            display: 'flex',
            flexDirection: 'column',
            justifyContent: 'space-between',
            cursor: 'pointer',
          }}
        >
          <div
            style={{
              fontSize: 11,
              textTransform: 'uppercase',
              letterSpacing: '0.06em',
              color: '#71717a',
            }}
          >
            {isFlipped ? 'Answer' : 'Question'}
          </div>

          <div style={{ fontSize: 16, lineHeight: 1.6, margin: '16px 0' }}>
            {isFlipped ? activeCard.answer : activeCard.question}
          </div>

          <div style={{ fontSize: 12, color: '#71717a' }}>
            {isFlipped ? 'Rate recall below' : 'Click card to flip'}
          </div>
        </div>

        <div
          style={{
            display: 'grid',
            gridTemplateColumns: 'repeat(4, minmax(0, 1fr))',
            gap: 8,
            marginTop: 12,
          }}
        >
          {(['again', 'hard', 'good', 'easy'] as const).map((rating) => (
            <button
              key={rating}
              type="button"
              disabled={!isFlipped}
              onClick={() => rateCard(rating)}
              style={{
                height: 34,
                borderRadius: 6,
                border: '1px solid rgba(255, 255, 255, 0.1)',
                background: isFlipped ? 'rgba(255, 255, 255, 0.04)' : 'transparent',
                color: isFlipped ? '#f4f4f5' : '#52525b',
                fontSize: 12,
                fontWeight: 500,
                textTransform: 'capitalize',
                cursor: isFlipped ? 'pointer' : 'not-allowed',
              }}
            >
              {rating} ({INTERVAL_DAYS[rating]}d)
            </button>
          ))}
        </div>
      </div>
    );
  },
});

On this page