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

  1. Scope and secret wrappers (PersonalScope, TeamScope, PermissionGuard, BlockScopeBar, VotingCard, TeamPoll, EnvSetupCard)
  2. Bento dashboard primitives (BentoGrid, BentoCard, StatCard, Chart) styled with --orbix-* CSS variables
  3. 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 throws UnknownSdkExportError to keep the core runtime bundle slim). Both Block Studio (VirtualBundler) and standalone npm builds resolve the full @orbixdocs/sdk/ui surface.
  • Styling in standalone npm builds: BentoGrid, BentoCard, StatCard, Chart, and EnvSetupCard use 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

ComponentKey propsPurpose
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)

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

On this page