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(orhttp://localhost:3000when running locally). No local Node.js setup or CLI installation is required for this guide.
Create a new block in Block Studio
- In the left sidebar of Orbix, click Block Studio.
- Start a new block project to open the Let's set up your block dialog.
- Enter
Quick Checklistas the block name and continue through setup, selecting Private visibility so the block is only visible in your workspace. - 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.
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
- Switch the center mode bar to Preview.
- Add an item and toggle its checkbox to confirm
useOrbixStateupdates immediately. - 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
- Click Publish in the top-right bar of the Block Studio editor.
- 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. - Open any document from the left sidebar (or click New Document).
- Type
/quick-checklist(or/and search for Quick Checklist) and pressEnter.
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
defineBlockandmanifest.jsondoes 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.