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
Mode 3 — Individual components · Import only what you need. Tree-shakeable, no renderer, you manage layout.
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—titleis now optional. The alert renders without a title when the prop is omitted. - Deprecated —
ComposeKitRendererlayoutprop — usebuilderStateinstead.layoutstill 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— addedsheetvariant: a panel that slides in from any edge viaside: 'left' | 'right' | 'top' | 'bottom'. SupportsshowCloseButtonanddismissable. - Update —
ComposeKitOverlay— yes footer buttons now auto-close the overlay by default. For async flows, callbtn.setLoading(true)to keep it open; the overlay closes automatically whensetLoading(false)is called. Overlays withdismissable: falserequire an explicitdialog.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— renameddataKeys→seriesKeysanddataKeyTypes→seriesKeyTypesfor consistency with other data-binding props. - New —
ComposeKitTree— addeddata,dataPath, anddataStoreIdprops for dynamic data binding, consistent withComposeKitChart.
v0.0.1-beta.8
- Fix —
ComposeKitClient.init()—clientIdis now optional whendisableCdn: true. Previously TypeScript requiredclientIdeven for layout-only or build-time usage where no CDN widget loading occurs. A discriminated union type now enforcesclientIdonly when CDN mode is active. - Internal — bundled
@bplcp/spinner,@bplcp/stepper,@bplcp/tabs,@bplcp/toast, and@bplcp/treeare no longer listed as npmdependencies. 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 anonSelectcallback. Import from@brainpiper/composekit/tree. - New —
ComposeKitCardcompound slot API — useComposeKitCard.Header,ComposeKitCard.Content, andComposeKitCard.Footeras named child slots for full layout control in code mode. The props-based API (header={{}},footer={{}}) remains available for JSON/renderer mode. - New —
ComposeKitAccordiontriggerandcontentprops now acceptstring | ReactNode, enabling rich content such as badges, icons, and custom layouts inside accordion items. - Breaking —
ComposeKitOverlayoverlayConfig.contentno longer accepts HTML strings. It now acceptsReactNode(JSX) only. This removes thedangerouslySetInnerHTMLXSS surface and enables full use of ComposeKit components and Tailwind classes inside overlays. Replace any string content with JSX. - Fix —
ComposeKitInput— inputs with nopatternprop 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— theerrorprop 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
onChangecallback signatures forComposeKitInput,ComposeKitTextarea,ComposeKitToggle,ComposeKitSelect, andComposeKitRadioGroup— the first argument is always the resolved value, not the browser event object. - Docs — corrected
ComposeKitRendererdata prop name in all documentation examples — the prop isdata, notdataModel. - Fix — telemetry now defaults to
falseacross all modes. PreviouslyComposeKitClient.init()andComposeKitRendererdefaulted totelemetry: true, silently sending plugin load events from end-user browsers. Passtelemetry: trueexplicitly to opt in.
v0.0.1-beta.6
- New —
ComposeKitSpinner— animated loading indicator with five sizes (xs→xl), optional label text, custom color, and anoverlaymode that renders a full-container backdrop for async operations. - New —
ComposeKitToast— global toast notification provider powered by Sonner. Supportssuccess,error,warning,info, and default variants, with descriptions, action buttons, and configurable position. Pairs with the exportedtoast()helper for programmatic triggering. - New —
ComposeKitTabs— tabbed panel component withdefaultandlinevariants, horizontal and vertical orientation, disabled tabs, card wrapper, andonTabChangecallback. Tabcontentaccepts a string or anyReactNode. - New —
ComposeKitStepper— multi-step progress indicator. Supportsdefaultandoutlinedvariants, horizontal and vertical orientations, clickable navigation, error states, optional labels, and inline step content. - Breaking —
ComposeKitChartdataprop type changed fromarraytoobject. It now behaves identically toComposeKitInput: the renderer injects the global data object anddataPathextracts the chart array from it. For standalone static arrays, useseries.
v0.0.1-beta.5
- New —
ComposeKitChartaddsseries(static data array, safe insideComposeKitRenderer— 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), anddataStoreId(bind to a shared global data store).
v0.0.1-beta.4
- New —
orientationprop added toComposeKitInput,ComposeKitTextarea,ComposeKitSelect, andComposeKitRadioGroup. 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
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