Block SDK · Reference
UI components
Scope wrappers, Bento primitives, and Tailwind UI components exported from @orbixdocs/sdk/ui.
@orbixdocs/sdk/ui groups three sets of components:
- Scope and secret wrappers (
PersonalScope,TeamScope,PermissionGuard,BlockScopeBar,VotingCard,TeamPoll,EnvSetupCard) - Bento dashboard primitives (
BentoGrid,BentoCard,StatCard,Chart) styled with--orbix-*CSS variables - Tailwind UI primitives (
Button,Card,Badge,Input,Tabs,Select,Dialog,Table, and related controls)
Using @orbixdocs/sdk/ui in Block Studio vs standalone npm
- Import path: Always import UI components from
@orbixdocs/sdk/ui(not from the root@orbixdocs/sdk, which throwsUnknownSdkExportErrorto keep the core runtime bundle slim). Both Block Studio (VirtualBundler) and standalone npm builds resolve the full@orbixdocs/sdk/uisurface. - Styling in standalone npm builds:
BentoGrid,BentoCard,StatCard,Chart, andEnvSetupCarduse inline--orbix-*CSS variables and work without extra CSS tooling. The Tailwind UI primitives (Button,Card,Tabs,Dialog,Table, etc.) emit Tailwind utility classes, so standalone npm apps should include Tailwind CSS in their build pipeline.
Scope and configuration components
| Component | Key props | Purpose |
|---|---|---|
PersonalScope | { children } | Sets the default scope of nested useOrbixState calls to 'personal'. |
TeamScope | { children } | Sets the default scope of nested useOrbixState calls to 'team'. |
BlockScopeBar | { blockId?, showPerspectiveSwitcher? } | Toolbar indicator showing active scope mode and collaborator perspective switcher. |
VotingCard | { pollKey?, question?, options? } | Pre-built poll UI backed by useVoting. |
EnvSetupCard | { envVar: string, label?, description?, placeholder?, props?, onSave? } | Renders a masked input for an unconfigured environment key and saves it to BlockSecretsManager. |
Bento primitives (--orbix-* styled)
import {
BentoGrid,
BentoCard,
StatCard,
Chart,
} from '@orbixdocs/sdk/ui';
export function MetricsOverview() {
return (
<BentoGrid columns={2} gap={12}>
<StatCard
label="Active Issues"
value={18}
delta="-3 this week"
trend="down"
/>
<BentoCard title="Throughput" subtitle="Completed items per day">
<Chart
type="bar"
height={120}
data={[
{ label: 'Mon', value: 4 },
{ label: 'Tue', value: 7 },
{ label: 'Wed', value: 6 },
]}
/>
</BentoCard>
</BentoGrid>
);
}Bento prop summary
BentoGrid:{ columns?: 1 | 2 | 3 | 4 | 6 | 12; gap?: number | string; children }BentoCard:{ title?: string; subtitle?: string; colSpan?: number; rowSpan?: number; headerRight?: ReactNode; children }StatCard:{ label: string; value: string | number; delta?: string; trend?: 'up' | 'down' | 'neutral'; icon?: ReactNode }Chart:{ data: Array<{ label?: string; name?: string; value: number }>; type?: 'area' | 'line' | 'bar'; height?: number; color?: string }
Tailwind UI primitives (npm subpath)
Available exports from @orbixdocs/sdk/ui:
- Buttons & badges:
Button(variant?: 'default' | 'primary' | 'destructive' | 'danger' | 'outline' | 'secondary' | 'ghost' | 'link',size?: 'default' | 'sm' | 'md' | 'lg' | 'icon',isLoading?: boolean),Badge(variant?: 'default' | 'secondary' | 'destructive' | 'outline' | 'success' | 'warning' | 'info') - Forms:
Input,Textarea,Label,Switch,Checkbox,Slider,RadioGroup,RadioGroupItem,Select(SelectTrigger,SelectValue,SelectContent,SelectItem) - Layout & data:
Card(CardHeader,CardTitle,CardDescription,CardContent,CardFooter),Table(TableHeader,TableBody,TableRow,TableHead,TableCell),Tabs(TabsList,TabsTrigger,TabsContent),Accordion,Separator,ScrollArea,Skeleton,Progress,Avatar,Alert - Overlays:
Dialog,Popover,DropdownMenu,Tooltip - Class helper:
cn(...inputs)