Marketplace Build Component

Build UI with Blok Design System

You are helping the user build UI components for a Sitecore Marketplace app using the Blok design system (Sitecore's shadcn-based component library).

Key Principles

1. Always use Blok components — they match the Sitecore host UI and support light/dark themes automatically 2. SDK data integration — use loading states (Skeleton) and error states (Alert) when fetching SDK data 3. Extension point awareness — different extension types have different UI constraints (see below) 4. Responsive — components render inside iframes of varying sizes

Installing Components

Blok components are installed via the shadcn CLI:

# Install the Blok theme (required first)
npx shadcn@latest add https://marketplace-sdk.sitecorecloud.io/r/blok-theme.json

# Install individual components
npx shadcn@latest add https://marketplace-sdk.sitecorecloud.io/r/<component-name>.json

See blok-components.md for the full component catalog with install commands.

UI Patterns by Extension Type

Compact Field (custom-field)

• Very limited space (~300px wide, variable height)
• Use: Input, Select, Badge, small inline components
• Avoid: Tables, large layouts, modals

Dashboard Widget

• Medium space (~400x300px default, resizable)
• Use: Cards, Charts, Stats, compact Tables
• Good for: Summary data, quick actions

Pages Context Panel

• Side panel (~350px wide, full height)
• Use: Vertical layouts, Lists, Accordion, Tabs
• Good for: Contextual info about current page, actions

Fullscreen

• Full viewport within the Sitecore shell
• Use: Any components, complex layouts, Tables, Forms
• Good for: Full CRUD interfaces, dashboards, settings

Standalone

• Independent page, not in Sitecore shell
• Use: Any components, full creative freedom
• Good for: Public-facing pages, OAuth callbacks

SDK Data Integration Pattern

"use client";

import { useEffect, useState } from "react";
import { useMarketplaceClient, useAppContext } from "@/components/providers/marketplace";
import { Skeleton } from "@/components/ui/skeleton";
import { Alert, AlertDescription } from "@/components/ui/alert";

export function MyComponent() {
  const { client } = useMarketplaceClient();
  const appContext = useAppContext();
  const [error, setError] = useState<string | null>(null);

  const loading = !appContext;

  if (loading) return <Skeleton className="h-32 w-full" />;
  if (error) return <Alert variant="destructive"><AlertDescription>{error}</AlertDescription></Alert>;

  return <div>{/* Render data */}</div>;
}

Reference Files

• Blok Components — Full component catalog with install commands

Blok Component Catalog

All components are installed via npx shadcn@latest add <url> where the URL is https://marketplace-sdk.sitecorecloud.io/r/<name>.json.

Theme (install first)

Layout & Structure

Forms & Input

Data Display

Feedback & Status

Navigation

Typography & Media

Installing Multiple Components

# Install several at once
npx shadcn@latest add https://marketplace-sdk.sitecorecloud.io/r/card.json https://marketplace-sdk.sitecorecloud.io/r/button.json https://marketplace-sdk.sitecorecloud.io/r/input.json https://marketplace-sdk.sitecorecloud.io/r/skeleton.json https://marketplace-sdk.sitecorecloud.io/r/alert.json

Usage Pattern

import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
import { Button } from "@/components/ui/button";
import { Skeleton } from "@/components/ui/skeleton";

export function MyWidget() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Widget Title</CardTitle>
      </CardHeader>
      <CardContent>
        <p>Content here</p>
        <Button>Action</Button>
      </CardContent>
    </Card>
  );
}