Skip to Content
OrbixDocs
Block SDK · Getting started

Build your first block

Create a stateful checklist block in Block Studio, publish it privately, and insert it into a page.

In this tutorial, you will build a small checklist block inside Block Studio, test its state in the live preview, publish it privately to your workspace, and insert it into a document with the / slash menu.

What you'll learn

  • How to create a block project in Block Studio
  • How to persist block data with useOrbixState
  • How to respect read-only pages via props.isReadOnly
  • How to publish a block privately and insert it into a document

Prerequisites

  • An open Orbix workspace at https://app.orbix.so (or http://localhost:3000 when running locally). No local Node.js setup or CLI installation is required for this guide.

Create a new block in Block Studio

  1. In the left sidebar of Orbix, click Block Studio.
  2. Start a new block project to open the Let's set up your block dialog.
  3. Enter Quick Checklist as the block name and continue through setup, selecting Private visibility so the block is only visible in your workspace.
  4. Once the editor opens, switch the top-center mode toggle from Chat or Preview to Code.

Write the block component

Replace the main entry file (src/index.tsx or App.tsx in the file tree) with the following code. Keep the id in manifest unique to your namespace — never start an id with com.orbix., which is reserved for built-in blocks.

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

interface TodoItem {
  id: string;
  text: string;
  done: boolean;
}

interface ChecklistState {
  items: TodoItem[];
}

export default defineBlock({
  manifest: {
    id: 'my-first-checklist',
    name: 'Quick Checklist',
    version: '0.1.0',
    sdk: '^3.0.0',
    category: 'Productivity',
    slashShortcut: '/quick-checklist',
    surfaces: ['block'],
  },
  component(props: BlockRenderProps) {
    const [state, setState] = useOrbixState<ChecklistState>(props, {
      items: [{ id: '1', text: 'Try toggling this item', done: false }],
    });
    const [draft, setDraft] = useState('');

    const addItem = () => {
      const trimmed = draft.trim();
      if (!trimmed || props.isReadOnly) return;
      setState((prev) => ({
        items: [
          ...prev.items,
          { id: String(Date.now()), text: trimmed, done: false },
        ],
      }));
      setDraft('');
    };

    const toggleItem = (id: string) => {
      if (props.isReadOnly) return;
      setState((prev) => ({
        items: prev.items.map((item) =>
          item.id === id ? { ...item, done: !item.done } : item
        ),
      }));
    };

    return (
      <div
        style={{
          padding: 16,
          borderRadius: 12,
          background: 'var(--orbix-card-bg, #16171b)',
          border: '1px solid var(--orbix-surface-border, #2a2b32)',
          color: 'var(--orbix-text-primary, #f4f4f5)',
          display: 'flex',
          flexDirection: 'column',
          gap: 10,
        }}
      >
        <strong style={{ fontSize: 14 }}>Quick Checklist</strong>

        <ul style={{ listStyle: 'none', padding: 0, margin: 0, display: 'grid', gap: 6 }}>
          {state.items.map((item) => (
            <li key={item.id} style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
              <input
                type="checkbox"
                checked={item.done}
                disabled={props.isReadOnly}
                onChange={() => toggleItem(item.id)}
              />
              <span
                style={{
                  textDecoration: item.done ? 'line-through' : 'none',
                  color: item.done
                    ? 'var(--orbix-text-secondary, #a1a1aa)'
                    : 'var(--orbix-text-primary, #f4f4f5)',
                }}
              >
                {item.text}
              </span>
            </li>
          ))}
        </ul>

        {!props.isReadOnly && (
          <div style={{ display: 'flex', gap: 8 }}>
            <input
              type="text"
              value={draft}
              onChange={(e) => setDraft(e.target.value)}
              onKeyDown={(e) => {
                if (e.key === 'Enter') addItem();
              }}
              placeholder="Add an item..."
              style={{
                flex: 1,
                padding: '6px 10px',
                borderRadius: 8,
                background: 'var(--orbix-surface-bg, #101114)',
                border: '1px solid var(--orbix-surface-border, #2a2b32)',
                color: 'var(--orbix-text-primary, #f4f4f5)',
              }}
            />
            <button type="button" onClick={addItem}>
              Add
            </button>
          </div>
        )}
      </div>
    );
  },
});

Click Save in the top-right bar of the editor.

Test in the live preview

  1. Switch the center mode bar to Preview.
  2. Add an item and toggle its checkbox to confirm useOrbixState updates immediately.
  3. If your code throws a syntax or runtime error, click the Show Console terminal icon next to Save in the top-right bar to inspect the compiler or runtime message.

Publish privately and insert into a page

  1. Click Publish in the top-right bar of the Block Studio editor.
  2. Confirm the block name and icon, choose Private as the target, and finish publishing. Private blocks are saved to your browser storage (IndexedDB + localStorage) and registered in your workspace's block registry so they persist across reloads.
  3. Open any document from the left sidebar (or click New Document).
  4. Type /quick-checklist (or / and search for Quick Checklist) and press Enter.

Your block mounts inline on the page. Add a second instance of /quick-checklist below the first one and toggle an item — each block instance has its own isolated state.

Next steps

  • Learn what each part of defineBlock and manifest.json does in Anatomy of a block.
  • Add per-user view state (such as personal filter tabs) alongside shared items in Store and sync state.
  • Understand why capabilities behave differently once a block is placed in a document in Develop and debug.

On this page