quick-builder-react

React SDK for Quick Builder - components and hooks for rendering Quick Builder content in React applications.

Installation

npm install quick-builder-react

Quick Start

With Provider (Recommended)

import { BuilderProvider, BuilderContent } from 'quick-builder-react';

function App() {
  return (
    <BuilderProvider apiKey="your-api-key">
      <BuilderContent slug="homepage" />
    </BuilderProvider>
  );
}

Standalone (Without Provider)

import { BuilderContent } from 'quick-builder-react';

function Page() {
  return (
    <BuilderContent
      apiKey="your-api-key"
      slug="homepage"
      loading={<div>Loading...</div>}
      notFound={<div>Page not found</div>}
    />
  );
}

Server-Side Rendering (Next.js)

import { BuilderContent, createClient } from 'quick-builder-react';

const client = createClient({ apiKey: process.env.BUILDER_API_KEY! });

export default async function Page({ params }: { params: { slug: string } }) {
  const content = await client.getContent({ slug: params.slug });

  if (!content) {
    notFound();
  }

  return <BuilderContent content={content} />;
}

export async function generateStaticParams() {
  const pages = await client.getAllContent();
  return pages.map((page) => ({ slug: page.slug }));
}

API Reference

<BuilderProvider>

Wrap your app to provide API configuration to all BuilderContent components.

<BuilderProvider
  apiKey="your-api-key"      // Required
  apiHost="https://..."       // Optional: custom API host
  preview={false}             // Optional: enable preview mode
  components={{               // Optional: register custom components
    CustomHero: MyHeroComponent,
  }}
>
  {children}
</BuilderProvider>

<BuilderContent>

Render Quick Builder content.

<BuilderContent
  // Content source (one required)
  slug="homepage"             // Fetch by slug
  contentId="abc123"          // Fetch by ID
  content={prefetchedContent} // Pre-fetched content (SSR)

  // Configuration
  apiKey="xxx"                // Required if not using Provider
  preview={false}             // Enable preview mode

  // Custom components for this content
  components={{
    CustomHero: MyHeroComponent,
  }}

  // Callbacks
  onLoad={(content) => {}}    // Called when content loads
  onError={(error) => {}}     // Called on error

  // Fallbacks
  loading={<Loading />}       // Loading state
  notFound={<NotFound />}     // Not found state

  // Wrapper props
  className="my-class"
  style={{ padding: 20 }}
/>

<BuilderBlocks>

Lower-level component for rendering parsed content.

import { BuilderBlocks, parseContent } from 'quick-builder-react';

const parsed = parseContent(content);
return <BuilderBlocks node={parsed} />;

useBuilderContent

Hook for fetching content with more control.

import { useBuilderContent, BuilderBlocks } from 'quick-builder-react';

function Page() {
  const { content, parsed, isLoading, error, refetch } = useBuilderContent({
    slug: 'homepage',
    // apiKey: 'xxx',  // Required if not using Provider
  });

  if (isLoading) return <Loading />;
  if (error) return <Error message={error.message} />;
  if (!parsed) return <NotFound />;

  return <BuilderBlocks node={parsed} />;
}

useBuilderContext

Access the Builder context within Provider.

import { useBuilderContext } from 'quick-builder-react';

function MyComponent() {
  const { client, preview, components } = useBuilderContext();
  // ...
}

Custom Components

Register custom components to be rendered by Quick Builder content.

Global Registration

import { registerComponent, registerComponents } from 'quick-builder-react';

// Single component
registerComponent('CustomHero', MyHeroComponent);

// Multiple components
registerComponents({
  CustomHero: MyHeroComponent,
  CustomPricing: MyPricingComponent,
});

Via Provider

<BuilderProvider
  apiKey="xxx"
  components={{
    CustomHero: MyHeroComponent,
    CustomPricing: MyPricingComponent,
  }}
>
  {children}
</BuilderProvider>

Via BuilderContent

<BuilderContent
  slug="homepage"
  components={{
    CustomHero: MyHeroComponent,
  }}
/>

TypeScript

Full TypeScript support included.

import type {
  BuilderContentProps,
  BuilderBlocksProps,
  BuilderProviderProps,
  UseBuilderContentResult,
  BuilderContentType,
  ParsedNode,
} from 'quick-builder-react';

Requirements

• React 18+
• Node.js 18+

Related Packages

• quick-builder-sdk - Core SDK (included as dependency)
• quick-builder-nextjs - Next.js integration (coming soon)

License

MIT