ZOIQ

React component library and framework with project-key-driven theme, hooks, and UI primitives. Use a single project key to auto-configure colors, fonts, and branding across your app.

Install

npm install @zoiq.io/dev-kit

Peer dependencies: react, react-dom (>=18), class-variance-authority, lucide-react.

CSS (required for apps that do not compile Tailwind from this package)

The dev-kit ships a pre-built Tailwind v4 bundle (dist/zoiq.css). Import it once at app startup:

import '@zoiq.io/dev-kit/zoiq.css'

If your app already runs Tailwind and scans @zoiq.io/dev-kit, you can omit this import to avoid duplicate utilities.

Vite (or similar) + Tailwind v3: PostCSS may try to run Tailwind v3 on the pre-built file and error on @layer. Either:

• Inject the string and skip PostCSS (example for Vite):

  import zoiqCss from '@zoiq.io/dev-kit/zoiq.css?raw'
  const el = document.createElement('style')
  el.textContent = zoiqCss
  document.head.appendChild(el)

• Or configure PostCSS so Tailwind does not process node_modules/@zoiq.io/dev-kit/**/*.css.

Quick start

Wrap your app with ZOIQProvider and pass your project key (and optional API base URL):

import { ZOIQProvider, Page, Header, Text, useProjectSettings } from 'zoiq'

function App() {
  return (
    <ZOIQProvider projectKey="your-project-id" baseUrl="https://your-portal.com">
      <Page>
        <Header left={<Logo />} right={<UserMenu />} />
        <Text>Content with theme applied</Text>
      </Page>
    </ZOIQProvider>
  )
}

ZOIQProvider

| Prop | Type | Description | | -------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | projectKey | string | Required. Project ID or public front-end key used to fetch theme and config. | | apiBaseUrl | string | Optional. Base URL for the project config API. Defaults to window.location.origin (same origin). | | fetchProjectConfig | (key: string) => Promise<ProjectSettings \| null> | Optional. Custom fetcher; if provided, apiBaseUrl is ignored for config. |

The provider:

1. Fetches project theme (styleGuide, branding, definedColors, navbarSettings) from GET {apiBaseUrl}/api/zoiq/project/{projectKey}.
2. Applies theme by setting CSS variables on document.documentElement and optional font links.
3. Exposes the same config via context for useProjectSettings and other hooks.

Hooks

useProjectSettings()

Returns the full project theme/settings (same data the provider used to apply theme). Use within ZOIQProvider.

const { data, loading, error, refetch } = useProjectSettings()
// data: ProjectSettings | null (styleGuide, branding, definedColors, navbarSettings)

useSectionFlags()

Returns which section IDs are enabled or disabled for the current project (e.g. for feature gating or nav). Uses GET {apiBaseUrl}/api/zoiq/project/{projectKey}/sections.

const { enabledIds, disabledIds, loading, error, refetch } = useSectionFlags()
// enabledIds: Set<string>, disabledIds: Set<string>

useZOIQApi<T>(entity, options?)

Fetches custom entity data for the current project. Uses GET {apiBaseUrl}/api/zoiq/project/{projectKey}/data/{entity}?id=....

const { data, loading, error, refetch } = useZOIQApi<PageType>('pages', { id: 'abc' })

Supported entities (when using the default portal API): pages, siteData.

Components

• Atoms: Text, Title, Subtitle, ScrollButton, ToggleTheme
• Molecules: Section, ToastContainer (placeholder; use your own toast library)
• Layout: Page, Header, Footer, SecondarySidebar

All components use CSS variables (e.g. var(--primary), var(--text-primary)) so ZOIQProvider’s theme applies automatically.

API (backend)

The default client expects these endpoints on the host (e.g. your portal):

• GET /api/zoiq/project/[projectKey] → project theme (styleGuide, branding, definedColors, navbarSettings)
• GET /api/zoiq/project/[projectKey]/sections → { enabledIds: string[], disabledIds: string[] }
• GET /api/zoiq/project/[projectKey]/data/[entity]?id=... → entity data (e.g. pages, siteData)

You can bypass these by passing a custom fetchProjectConfig to ZOIQProvider.

License

See repository license.