ComposeKit Docs
Getting Started

ComposeKit

ComposeKit is a React SDK by BrainPiper. It renders UI layouts designed visually in BrainPiper Studio directly inside your React app — without writing layout code by hand. It also ships every component as a standalone import, so you can use individual pieces without the ComposeKitRenderer for rendering widgets.

Prerequisites

React 18 or 19. A Client ID from BrainPiper Studio.

1. Install
$ npm install @brainpiper/composekit lucide-react react react-dom
2. Initialise
main.tsx
import { ComposeKitClient } from '@brainpiper/composekit';
import '@brainpiper/composekit/dist/style.css';

// Call once at your app entry point
ComposeKitClient.init({
    clientId: 'YOUR_CLIENT_ID',
});
3. Render a widget
MyPage.tsx
import { ComposeKitRenderer } from '@brainpiper/composekit';

function MyPage() {
    return (
        <ComposeKitRenderer
            widgetId="your-widget-id"
            data={{ userId: 'u_001', name: 'Jane' }}
            onUpdate={(dataPath, value) => {
                console.log('Field updated:', dataPath, value);
            }}
        />
    );
}

Three ways to use ComposeKit

Depending on your deployment needs, ComposeKit supports three distinct render modes. Use the sidebar to explore each one — every section shows the approach, the tradeoffs, and a live demo you can interact with directly.

Mode 1 — CDN · Plugins load from BrainPiper CDN at runtime. Smallest bundle, auto-updates, requires internet.
Mode 2 — Build-time · All plugins bundled into your app. Pass a widgetId (Studio-built widget) or a layout JSON (static or from ComposeKitServer) — widgetId takes priority if both are provided. Because the widget composition is unknown at build time, all plugins must be included in the bundle. Requires internet when using widgetId.
Mode 3 — Individual components · Import only what you need. Tree-shakeable, no renderer, you manage layout.

Changelog
v0.0.1-beta.11
  • Update — ComposeKitAlert — title is now optional. The alert renders without a title when the prop is omitted.
  • Deprecated — ComposeKitRenderer layout prop — use builderState instead. layout still works but logs a deprecation warning and will be removed in a future release.
  • Update — Minor fixes across components.
v0.0.1-beta.10
  • New — ComposeKitOverlay — added sheet variant: a panel that slides in from any edge via side: 'left' | 'right' | 'top' | 'bottom'. Supports showCloseButton and dismissable.
  • Update — ComposeKitOverlay — yes footer buttons now auto-close the overlay by default. For async flows, call btn.setLoading(true) to keep it open; the overlay closes automatically when setLoading(false) is called. Overlays with dismissable: false require an explicit dialog.close().
  • New — ComposeKitPagination — standalone pagination component with page navigation, configurable records-per-page, and total count display. Import from @brainpiper/composekit/pagination.
  • New — ComposeKitNavigationMenu — horizontal navigation menu with support for nested items and active state. Import from @brainpiper/composekit/navigation-menu.
  • Update — ComposeKitGrid — added props to hide or disable the records-per-page selector, hide the total record count, and customize the pagination panel layout.
v0.0.1-beta.9
  • Breaking — ComposeKitChart — renamed dataKeys → seriesKeys and dataKeyTypes → seriesKeyTypes for consistency with other data-binding props.
  • New — ComposeKitTree — added data, dataPath, and dataStoreId props for dynamic data binding, consistent with ComposeKitChart.
v0.0.1-beta.8
  • Fix — ComposeKitClient.init() — clientId is now optional when disableCdn: true. Previously TypeScript required clientId even for layout-only or build-time usage where no CDN widget loading occurs. A discriminated union type now enforces clientId only when CDN mode is active.
  • Internal — bundled @bplcp/spinner, @bplcp/stepper, @bplcp/tabs, @bplcp/toast, and @bplcp/tree are no longer listed as npm dependencies. They are webpack-bundled into the package and were never installable as standalone npm packages.
v0.0.1-beta.7
  • New — ComposeKitTree — hierarchical tree view with lazy-loaded children, multi-select, drag-and-drop reordering, custom icons, expand/collapse control, and an onSelect callback. Import from @brainpiper/composekit/tree.
  • New — ComposeKitCard compound slot API — use ComposeKitCard.Header, ComposeKitCard.Content, and ComposeKitCard.Footer as named child slots for full layout control in code mode. The props-based API (header={{}}, footer={{}}) remains available for JSON/renderer mode.
  • New — ComposeKitAccordion trigger and content props now accept string | ReactNode, enabling rich content such as badges, icons, and custom layouts inside accordion items.
  • Breaking — ComposeKitOverlay overlayConfig.content no longer accepts HTML strings. It now accepts ReactNode (JSX) only. This removes the dangerouslySetInnerHTML XSS surface and enables full use of ComposeKit components and Tailwind classes inside overlays. Replace any string content with JSX.
  • Fix — ComposeKitInput — inputs with no pattern prop set no longer trigger browser native validation. The empty string default was being passed to the native <input> element, causing all non-empty values to be rejected silently.
  • Fix — ComposeKitInput, ComposeKitTextarea, ComposeKitToggle, ComposeKitSelect, ComposeKitRadioGroup — the error prop now updates reactively when its value changes externally (e.g. driven by parent validation state). Previously, only the initial value was applied and subsequent prop changes were ignored.
  • Docs — corrected onChange callback signatures for ComposeKitInput, ComposeKitTextarea, ComposeKitToggle, ComposeKitSelect, and ComposeKitRadioGroup — the first argument is always the resolved value, not the browser event object.
  • Docs — corrected ComposeKitRenderer data prop name in all documentation examples — the prop is data, not dataModel.
  • Fix — telemetry now defaults to false across all modes. Previously ComposeKitClient.init() and ComposeKitRenderer defaulted to telemetry: true, silently sending plugin load events from end-user browsers. Pass telemetry: true explicitly to opt in.
v0.0.1-beta.6
  • New — ComposeKitSpinner — animated loading indicator with five sizes (xs → xl), optional label text, custom color, and an overlay mode that renders a full-container backdrop for async operations.
  • New — ComposeKitToast — global toast notification provider powered by Sonner. Supports success, error, warning, info, and default variants, with descriptions, action buttons, and configurable position. Pairs with the exported toast() helper for programmatic triggering.
  • New — ComposeKitTabs — tabbed panel component with default and line variants, horizontal and vertical orientation, disabled tabs, card wrapper, and onTabChange callback. Tab content accepts a string or any ReactNode.
  • New — ComposeKitStepper — multi-step progress indicator. Supports default and outlined variants, horizontal and vertical orientations, clickable navigation, error states, optional labels, and inline step content.
  • Breaking — ComposeKitChart data prop type changed from array to object. It now behaves identically to ComposeKitInput: the renderer injects the global data object and dataPath extracts the chart array from it. For standalone static arrays, use series.
v0.0.1-beta.5
  • New — ComposeKitChart adds series (static data array, safe inside ComposeKitRenderer — never overwritten by the renderer's global data), dataPath (dot-path to extract a dynamic array from the renderer's data object or data store), and dataStoreId (bind to a shared global data store).
v0.0.1-beta.4
  • New — orientation prop added to ComposeKitInput, ComposeKitTextarea, ComposeKitSelect, and ComposeKitRadioGroup. Accepts 'vertical' (default), 'horizontal', or 'responsive'.
v0.0.1-beta.3
  • Docs — component readme files updated
v0.0.1-beta.2
  • New — ComposeKitChart — line, bar, area, pie/donut, composed, and radar chart types powered by Recharts. Import from @brainpiper/composekit/chart.
v0.0.1-beta.1 — initial release
  • 21 components: Button, ButtonGroup, Overlay, Input, Textarea, Select, RadioGroup, Toggle, Heading, Paragraph, Badge, Alert, Avatar, Image, Separator, Card, Section, Accordion, List, Carousel, Grid
  • ComposeKitRenderer with CDN and build-time modes
  • ComposeKitClient with theme and locale support
Beta limitations — UI orchestration (workflows, localization, design system tokens, API endpoints) not yet supported
The following Studio-configured behaviours are not executed when a widget is rendered via ComposeKitRenderer in this beta version. The widget renders correctly and data binding works as normal.
  • Workflows — plugin event handlers (e.g. button click triggering an API call or navigation) are not executed
  • Localization — locale-aware field values and translations are not applied
  • Design system tokens — tokens configured in the Studio design system are not applied; use ComposeKitClient.setTheme() to theme components instead
  • API endpoints — data source bindings configured in Studio are not fetched
Full UI orchestration support is planned for a future release.