incld
Start free
Docs/React UI

Find the framework route, component prop, SDK method, or HTTP contract you need.

Provider, theming, and shared behavior

Every React package reads the browser client, live refresh boundary, locale, appearance, and error reporter from IncldProvider. The provider calls your same-origin proxy; your backend injects the user identity.

Install and import styles

npm install @incld/client @incld/react
@import "@incld/react/styles.css";
@import "@incld/react-schedules/styles.css";
@import "@incld/react-approvals/styles.css";
@import "@incld/react-bulk/styles.css";
@import "@incld/react-audit/styles.css";

IncldProvider

<IncldProvider
 baseUrl="/api/incld"
 refreshInterval={5000}
 appearance={{
  colorScheme: "system",
  accentColor: "emerald",
  radius: "medium",
  density: "comfortable",
 }}
 labels={{ optional: "Optional" }}
 onError={error => telemetry.capture(error, {
  code: error.code,
  requestId: error.requestId,
 })}
>
 {children}
</IncldProvider>
PropTypeDefault / behavior
client IncldBrowser? Optional preconstructed browser client.
baseUrl string? /api/incld; ignored when client is supplied.
appearance IncldAppearance? System color scheme, indigo accent, medium radius, comfortable density.
labels Record<string, string>? Shared label overrides for localization.
refreshInterval number | false? 5000ms. Mounted query hooks refresh while visible; positive values below 1000ms are clamped. false disables automatic refresh.
onError (IncldError) => void? Called by feature mutations after errors are normalized.
className string? Added to the provider's .incld-root wrapper.
style CSSProperties? Inline wrapper styles; explicit style values win over mapped theme variables.
children ReactNode Required component tree.

View-scoped automatic refresh

Only query hooks mounted in the current application view make requests. Refresh pauses while the document is hidden and runs immediately when it becomes visible again. Set refreshInterval to false for manual-only behavior, or call useIncld().refresh() after an application event.

Appearance and CSS variables

OptionValues
colorScheme light | dark | system
accentColor indigo | blue | emerald | amber | rose
radius small | medium | large
density compact | comfortable

Set arbitrary tokens with appearance.variables. The provider maps camelCase keys to CSS custom properties on its root wrapper.

Variable keysCSS properties
accent, accentHover, accentContrast, accentInk, accentSoft --incld-accent, --incld-accent-hover, --incld-accent-contrast, --incld-accent-ink, --incld-accent-soft
background, surface, surfaceHover, border, text, muted --incld-bg, --incld-surface, --incld-surface-hover, --incld-border, --incld-text, --incld-muted
danger/dangerSoft/dangerBorder, success/…, warning/… --incld-danger/-soft/-border, --incld-success/-soft/-border, --incld-warning/-soft/-border
radius, spacing, shadow, fontFamily, fontSize, lineHeight, focusRing --incld-radius, --incld-space, --incld-shadow, --incld-font-family, --incld-font-size, --incld-line-height, --incld-focus-ring 
.my-incld-surface {
 --incld-accent: #7c3aed;
 --incld-accent-hover: #6d28d9;
 --incld-accent-soft: #f5f3ff;
 --incld-bg: #ffffff;
 --incld-surface: #fafafa;
 --incld-border: #e5e7eb;
 --incld-text: #111827;
 --incld-muted: #6b7280;
 --incld-danger: #b91c1c;
 --incld-success: #047857;
 --incld-radius: 14px;
 --incld-space: 16px;
 --incld-shadow: 0 18px 50px rgb(15 23 42 / 14%);
}

Shared async states

interface AsyncViewProps {
 loading?: ReactNode
 empty?: ReactNode
 error?: (error: IncldError, retry: () => void) => ReactNode
}

List and details components provide accessible loading, empty, and error defaults. Replace them through these props without replacing data behavior. Hooks return data, error, status, and refresh, where status is idle, loading, success, or error.

Exported primitives and hook

ExportPublic interface
useIncld() Returns client, resolved appearance, labels, version, resolved refreshInterval, refresh(), and reportError().
useAsyncResource(loader, deps) Abort-aware loader returning data, error, status, and refresh.
useIncldLabel(key, fallback) Returns a provider label override or fallback text.
IncldButton Native button props plus busy; adds aria-busy and disables while busy.
IncldDialog open, onOpenChange, title, description?, className?, backdropClassName?, closeLabel?, children; traps focus, closes on Escape/backdrop, restores focus.
IncldSpinner label?, className?; accessible role=status loading state.
IncldEmptyState title, description?, className?.
IncldErrorState error, retry, className?; accessible role=alert.
IncldFieldError error?, fields (string or string[]), id?, className?; renders deduplicated field messages.
errorMessagesFor(error, ...fields) Returns deduplicated validation messages for the requested API field names.

Generated TypeScript signatures

This table is generated directly from exported interfaces during the SDK build. Behavioral defaults remain documented above; requiredness and types below fail CI if declarations drift.

InterfacePropTypeRequired
AsyncViewProps loading ReactNode No
AsyncViewProps empty ReactNode No
AsyncViewProps error (error: IncldError, retry: () => void) => ReactNode No
IncldAppearance colorScheme 'light' | 'dark' | 'system' No
IncldAppearance accentColor 'indigo' | 'blue' | 'emerald' | 'amber' | 'rose' No
IncldAppearance radius 'small' | 'medium' | 'large' No
IncldAppearance density 'compact' | 'comfortable' No
IncldAppearance variables IncldThemeVariables No
IncldButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> busy boolean No
IncldDialogProps open boolean Yes
IncldDialogProps onOpenChange (open: boolean) => void Yes
IncldDialogProps title string Yes
IncldDialogProps description string No
IncldDialogProps className string No
IncldDialogProps backdropClassName string No
IncldDialogProps closeLabel string No
IncldDialogProps children ReactNode Yes
IncldEmptyStateProps title string Yes
IncldEmptyStateProps description string No
IncldEmptyStateProps className string No
IncldErrorStateProps error IncldError Yes
IncldErrorStateProps retry () => void Yes
IncldErrorStateProps className string No
IncldFieldErrorProps error IncldError No
IncldFieldErrorProps fields string | string[] Yes
IncldFieldErrorProps id string No
IncldFieldErrorProps className string No
IncldProviderProps client IncldBrowser No
IncldProviderProps baseUrl string No
IncldProviderProps appearance IncldAppearance No
IncldProviderProps labels Record<string, string> No
IncldProviderProps refreshInterval number | false No
IncldProviderProps onError (error: IncldError) => void No
IncldProviderProps className string No
IncldProviderProps style CSSProperties No
IncldProviderProps children ReactNode Yes
IncldSpinnerProps label string No
IncldSpinnerProps className string No
IncldThemeVariables accent string No
IncldThemeVariables accentHover string No
IncldThemeVariables accentContrast string No
IncldThemeVariables accentInk string No
IncldThemeVariables accentSoft string No
IncldThemeVariables background string No
IncldThemeVariables surface string No
IncldThemeVariables surfaceHover string No
IncldThemeVariables border string No
IncldThemeVariables text string No
IncldThemeVariables muted string No
IncldThemeVariables danger string No
IncldThemeVariables dangerSoft string No
IncldThemeVariables dangerBorder string No
IncldThemeVariables success string No
IncldThemeVariables successSoft string No
IncldThemeVariables successBorder string No
IncldThemeVariables warning string No
IncldThemeVariables warningSoft string No
IncldThemeVariables warningBorder string No
IncldThemeVariables radius string No
IncldThemeVariables spacing string No
IncldThemeVariables shadow string No
IncldThemeVariables fontFamily string No
IncldThemeVariables fontSize string No
IncldThemeVariables lineHeight string No
IncldThemeVariables focusRing string No
@incld / API v1
Something not working? Troubleshooting →