Block SDK · Guides
Build multi-surface blocks
Adapt a single block across inline document canvases, split-view companion panels, and full-page workspace views.
An Orbix block can run in three host locations depending on what surfaces its manifest declares:
| Surface | Context flag | Where the user opens it |
|---|---|---|
'block' | isInlineBlock | Embedded inside a document via the / slash menu (default). |
'sidebar_panel' | isSplitView | Docked beside an open document in split view as a companion panel. |
'fullpage' | isGlobalView | Opened from the workspace sidebar as a standalone full-page view. |
Declaring supported surfaces
Add surfaces (and optionally type) to manifest.json or inline in defineBlock:
{
"id": "acme.reading-timer",
"name": "Reading Timer",
"version": "1.0.0",
"sdk": "^3.0.0",
"type": "hybrid",
"surfaces": ["block", "sidebar_panel", "fullpage"]
}'block'— inline document widget (surfaces: ['block']is the default when omitted).'app'— full-page or sidebar tool (surfaces: ['fullpage']or['fullpage', 'sidebar_panel']).'hybrid'— adapts across inline documents and workspace-level views.
Routing layouts with <SurfaceRouter> and useOrbixSurface
Use <SurfaceRouter> when each surface renders a distinct layout, or call useOrbixSurface() directly when sharing layout structure with conditional controls:
import {
defineBlock,
SurfaceRouter,
useOrbixDocument,
useOrbixState,
useOrbixSurface,
type BlockRenderProps,
} from '@orbixdocs/sdk';
interface TimerState {
targetMinutes: number;
}
function InlineWidget({ props }: { props: BlockRenderProps }) {
const [state, setState] = useOrbixState<TimerState>(props, { targetMinutes: 25 });
return (
<div
style={{
padding: 12,
borderRadius: 10,
background: 'var(--orbix-card-bg, #16171b)',
border: '1px solid var(--orbix-surface-border, #2a2b32)',
color: 'var(--orbix-text-primary, #f4f4f5)',
display: 'flex',
alignItems: 'center',
justifyContent: 'space-between',
}}
>
<span>Focus session: {state.targetMinutes} min</span>
<button
type="button"
disabled={props.isReadOnly}
onClick={() =>
setState((prev) => ({ targetMinutes: prev.targetMinutes + 5 }))
}
>
+5 min
</button>
</div>
);
}
function CompanionPanel() {
const { activeDocumentId } = useOrbixSurface();
const doc = useOrbixDocument();
return (
<div style={{ padding: 16, color: 'var(--orbix-text-primary, #f4f4f5)' }}>
<div style={{ fontWeight: 600, marginBottom: 6 }}>
Companion for {doc.pageTitle || activeDocumentId || 'current page'}
</div>
<div style={{ fontSize: 13, color: 'var(--orbix-text-secondary, #a1a1aa)' }}>
Estimated reading time: {Math.max(1, Math.ceil(doc.wordCount / 200))} min ({doc.wordCount} words)
</div>
</div>
);
}
function FullpageDashboard({ props }: { props: BlockRenderProps }) {
const { dimensions } = useOrbixSurface();
return (
<div style={{ padding: 24, color: 'var(--orbix-text-primary, #f4f4f5)' }}>
<h2 style={{ margin: '0 0 8px' }}>Reading Timer Overview</h2>
<p style={{ margin: '0 0 16px', color: 'var(--orbix-text-secondary, #a1a1aa)' }}>
Viewport width: {dimensions?.width ?? 'auto'}
</p>
<InlineWidget props={props} />
</div>
);
}
export default defineBlock({
manifest: {
id: 'acme.reading-timer',
name: 'Reading Timer',
version: '1.0.0',
sdk: '^3.0.0',
type: 'hybrid',
surfaces: ['block', 'sidebar_panel', 'fullpage'],
capabilities: {
document: ['read'],
},
},
component(props: BlockRenderProps) {
return (
<SurfaceRouter
block={<InlineWidget props={props} />}
sidebar_panel={<CompanionPanel />}
fullpage={<FullpageDashboard props={props} />}
/>
);
},
});Surface-specific state and document behavior
activeDocumentIdin'fullpage': When a user opens your block as a standalone full-page view, there is no surrounding document editor, soactiveDocumentIdisnullanduseOrbixDocument()returns empty defaults (wordCount: 0,headings: []). Guard document-dependent UI whenisGlobalViewistrue.- State scoping across surfaces: Inline
'block'instances storeteamstate on that specific document block'sprops. If a'fullpage'view needs to read or write state shared across the entire workspace rather than a single embedded block, pass{ workspaceWide: true }touseTeamStateoruseStorage. - Fallback rendering: If
SurfaceRouterdoes not receive a prop for the active surface, it rendersfallback(or falls back in order toblock,sidebar_panel, thenfullpage).