Skip to Content
OrbixDocs
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:

SurfaceContext flagWhere the user opens it
'block'isInlineBlockEmbedded inside a document via the / slash menu (default).
'sidebar_panel'isSplitViewDocked beside an open document in split view as a companion panel.
'fullpage'isGlobalViewOpened 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:

manifest.json
{
  "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:

src/ReadingTimerBlock.tsx
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

  • activeDocumentId in 'fullpage': When a user opens your block as a standalone full-page view, there is no surrounding document editor, so activeDocumentId is null and useOrbixDocument() returns empty defaults (wordCount: 0, headings: []). Guard document-dependent UI when isGlobalView is true.
  • State scoping across surfaces: Inline 'block' instances store team state on that specific document block's props. If a 'fullpage' view needs to read or write state shared across the entire workspace rather than a single embedded block, pass { workspaceWide: true } to useTeamState or useStorage.
  • Fallback rendering: If SurfaceRouter does not receive a prop for the active surface, it renders fallback (or falls back in order to block, sidebar_panel, then fullpage).

On this page