Connect blocks together
Publish typed output ports, subscribe to upstream inputs, and exchange events between blocks on the same page.
Blocks on the same Orbix page can pass data to one another through named output ports, input ports, and events managed by blockGraphEngine.
How ports work
- A producer block publishes values on a named port with
useBlockOutput(portName, value, metadata?). - A consumer block reads values from a port with
useBlockInput<T>(portName, defaultValue, options?). - Data flows in one direction through an in-memory directed acyclic graph (
blockGraphEngine) on the current page. Circular connections (A → B → A) are rejected automatically when wiring ports. - Port registrations happen inside React effects and clean up automatically when a block unmounts (including
React.StrictModedouble-mount cycles in development).
Supported port schemas
Declare the type on each port in manifest.inputs / manifest.outputs and in useBlockOutput metadata so the Data Connections modal can validate compatibility before wiring:
| Schema type | TypeScript payload | Typical use |
|---|---|---|
'number' | number | Totals, currency amounts, percentages, slider values, and gauges |
'string' | string | Selected filter values, status labels, search queries, and IDs |
'boolean' | boolean | Approval gates, toggles, and checklist completion flags |
'date' | string (ISO-8601) | Deadlines, milestone dates, and timeline ranges |
'array' / 'table-rows' | Record<string, unknown>[] | Database view rows, series points, and list items |
'object' | Record<string, unknown> | Structured JSON payloads (for example { amount: number, currency: string }) |
Producer and consumer example
Declare outputs and inputs on each block's manifest so Orbix and the block inspector know which ports exist and what data types they carry.
import {
defineBlock,
useOrbixState,
useBlockOutput,
useBlockInput,
type BlockRenderProps,
} from '@orbixdocs/sdk';
// 1. Producer block: publishes a numeric tax rate and base amount
export const PriceInputBlock = defineBlock({
manifest: {
id: 'acme.price-input',
name: 'Price Input',
version: '1.0.0',
sdk: '^3.0.0',
capabilities: {
blocks: ['events', 'connections'],
},
outputs: {
subtotal: { type: 'number', label: 'Subtotal' },
},
},
component(props: BlockRenderProps) {
const [state, setState] = useOrbixState(props, { subtotal: 100 });
// Publishes whenever state.subtotal changes; isPublic: true exposes the port to unwired blocks on the same page
useBlockOutput('subtotal', state.subtotal, {
type: 'number',
label: 'Subtotal',
isPublic: true,
});
return (
<div>
<label>
Subtotal:{' '}
<input
type="number"
disabled={props.isReadOnly}
value={state.subtotal}
onChange={(e) => setState({ subtotal: Number(e.target.value) || 0 })}
/>
</label>
</div>
);
},
});
// 2. Consumer block: subscribes to 'subtotal' and computes total with tax
export const TaxSummaryBlock = defineBlock({
manifest: {
id: 'acme.tax-summary',
name: 'Tax Summary',
version: '1.0.0',
sdk: '^3.0.0',
capabilities: {
blocks: ['events', 'connections'],
},
inputs: {
subtotal: { type: 'number', label: 'Subtotal' },
},
},
component() {
const subtotal = useBlockInput<number>('subtotal', 0);
const tax = subtotal * 0.18;
return (
<div>
<div>Subtotal: {subtotal.toFixed(2)}</div>
<div>Tax (18%): {tax.toFixed(2)}</div>
<strong>Total: {(subtotal + tax).toFixed(2)}</strong>
</div>
);
},
});Explicit connections vs page-wide public ports
useBlockInput('subtotal', 0) resolves upstream values in two ways:
- Wired graph connections or explicit
sourceBlockId: When two blocks are connected in the block graph (blockGraphEngine.connect) or when you passsourceBlockIdandsourcePort,useBlockInputreads that upstream port directly regardless ofisPublic. - Unwired page-wide matching by port name: When no explicit graph edge is wired,
useBlockInput('subtotal', 0)scans ports named'subtotal'on the page that were published with{ isPublic: true }.
To bind directly to a known upstream block ID or map a differently named port, pass sourceBlockId and sourcePort:
import { useBlockInput } from '@orbixdocs/sdk';
export function SpecificInput({ upstreamId }: { upstreamId: string }) {
const value = useBlockInput<number>('amount', 0, {
sourceBlockId: upstreamId,
sourcePort: 'subtotal',
});
return <span>Upstream amount: {value}</span>;
}Publishing multiple ports at once
If your block exposes several outputs derived from the same calculation, call useBlockOutputs with a record:
import { useBlockOutputs } from '@orbixdocs/sdk';
export function MetricsPublisher({ revenue, cost }: { revenue: number; cost: number }) {
useBlockOutputs(
{
revenue,
cost,
margin: revenue - cost,
},
{
revenue: { type: 'number', label: 'Revenue', isPublic: true },
cost: { type: 'number', label: 'Cost', isPublic: true },
margin: { type: 'number', label: 'Margin', isPublic: true },
}
);
return null;
}Discrete events (useBlockEvent and emitBlockEvent)
Ports represent continuous values (the latest number, filter string, or array). For one-off actions such as "reset all filters" or "refresh chart", use useBlockEvent and emitBlockEvent.
Always read useBlockId() at the top level of your component and pass it as the third argument to emitBlockEvent inside event handlers so the event is attributed to the right block instance:
import { useState } from 'react';
import { useBlockId, useBlockEvent, emitBlockEvent } from '@orbixdocs/sdk';
export function ResetTrigger() {
const blockId = useBlockId();
return (
<button
type="button"
onClick={() => emitBlockEvent('filters:reset', { at: Date.now() }, blockId)}
>
Reset page filters
</button>
);
}
export function ResetListener() {
const [lastReset, setLastReset] = useState<number | null>(null);
useBlockEvent('filters:reset', (payload: { at?: number }) => {
setLastReset(payload?.at ?? Date.now());
});
return <span>{lastReset ? `Reset at ${lastReset}` : 'Active'}</span>;
}Capabilities for block connections
- React SDK blocks:
blockGraphEngineenforcescapabilityEngine.verifyBlocks(...)('events'is included incommunitydefaults; declareblocks: ['events', 'connections'], plus'read'when reading cross-block state). - HTML / polyglot frames: Host RPC calls to
setPortOutputstrictly requireblocks: ['connections']inmanifest.capabilities. - Network tainting: Reading cross-block data (
blocks:read) on a community block marks that instance as tainted by workspace read, which blocks subsequent outbound external network calls viaorbixEgressFirewall.