@zickt/react

@zickt/react is the official React SDK for embedding the Zickt chat widget. It provides two usage patterns — a drop-in component (ZicktMessenger) for zero-configuration setup, and a context provider (ZicktProvider) with a useZickt hook for programmatic control from anywhere in your component tree.

Installation

npm install @zickt/react

Peer dependencies: React 18 or 19 and the corresponding react-dom.

Package size: Under 3 kB minified + brotli.

Overview

The package exports three runtime symbols and fourteen type symbols.

Runtime exports:

• ZicktMessenger — drop-in component; wraps ZicktProvider internally
• ZicktProvider — context provider; use when child components need useZickt
• useZickt — hook that returns the context value from the nearest ZicktProvider

Type exports:

ReactCommand, CSSColor, CSSFontFamily, CSSLength, CSSZIndex, ZicktAppearance, ZicktCallbacks, ZicktCompany, ZicktConfig, ZicktContextValue, ZicktIdentifyPayload, ZicktMessengerProps, ZicktProviderProps, ZicktUser

The SDK loads the Zickt CDN script (https://cdn.zickt.com/loader.js) at runtime and is SSR-safe: it performs no DOM operations when window is undefined.

ZicktMessenger

import { ZicktMessenger } from '@zickt/react';

export default function App() {
  return (
    <>
      <YourApp />
      <ZicktMessenger channelKey="your-channel-key" />
    </>
  );
}

ZicktMessenger is a drop-in component with no required configuration beyond channelKey. It renders nothing visible — the chat widget is injected into the page by the CDN SDK. Internally it renders <ZicktProvider {...props}><></></ZicktProvider>, so it accepts all ZicktConfig and ZicktCallbacks props but not children.

Props type: ZicktMessengerProps = ZicktConfig & ZicktCallbacks

Config props

Callback props

ZicktProvider

Use ZicktProvider when you need to call useZickt from child components — for example, to open the widget from a button deep in your component tree.

import { ZicktProvider } from '@zickt/react';

export default function App() {
  return (
    <ZicktProvider channelKey="your-channel-key">
      <YourApp />
    </ZicktProvider>
  );
}

Props type: ZicktProviderProps extends ZicktConfig, ZicktCallbacks

ZicktProviderProps accepts all the same config and callback props as ZicktMessenger, plus children:

Lifecycle behavior

• On mount, the CDN script is loaded once. If the script tag is already present in the DOM (added manually), no second tag is appended.
• After the script loads, the widget boots with the provided channelKey.
• When user, company, appearance, customLauncherSelector, or hideDefaultLauncher change after boot, the widget updates automatically without re-booting.
• Changing channelKey triggers a full shutdown and re-boot.
• On unmount, the widget shuts down and internal state resets.

useZickt

useZickt returns the ZicktContextValue from the nearest ZicktProvider. Call it from any component inside the provider tree.

import { useZickt } from '@zickt/react';

export function SupportButton() {
  const { show, isReady } = useZickt();

  return (
    <button onClick={show} disabled={!isReady}>
      Chat with us
    </button>
  );
}

Throws "useZickt must be used within a <ZicktProvider>" if called outside a provider.

Return type: ZicktContextValue

All methods are stable references created with useCallback and are safe to use in useEffect dependency arrays.

Types

ZicktConfig

Core configuration interface shared by ZicktMessenger, ZicktProvider, and the update method.

interface ZicktConfig {
  channelKey: string;
  user?: ZicktUser;
  company?: ZicktCompany;
  appearance?: ZicktAppearance;
  customLauncherSelector?: string;
  hideDefaultLauncher?: boolean;
}

ZicktUser

User identity passed at boot time via the user prop.

ZicktUser also accepts arbitrary custom attributes via an index signature: [key: string]: unknown.

ZicktCompany

Company identity passed at boot time via the company prop.

ZicktCompany also accepts arbitrary custom attributes via an index signature: [key: string]: unknown.

ZicktIdentifyPayload

Richer payload used with the identify() method. Use identify after the user logs in to associate a session with a known identity.

The company field within ZicktIdentifyPayload accepts id, name, domain, industry, size, plan, monthlySpend (number), and custom (arbitrary key-value pairs).

ZicktAppearance

All 14 appearance fields. All fields are optional. Changes to appearance after boot are applied via the update method automatically when passed as a prop, or manually via useZickt().update({ appearance: ... }).

Layout and theme:

Brand cohesion:

Polish:

CSS type aliases

CSSColor, CSSLength, and CSSFontFamily are documented string aliases — the SDK passes them to the underlying widget without runtime validation.

type CSSColor = string; // hex, rgb, hsl, or named color
type CSSLength = string; // must include units: '16px', '1rem', '50%', 'calc(100% - 20px)'
type CSSFontFamily = string; // e.g., '"Inter", sans-serif'
type CSSZIndex = number; // integer z-index value

ReactCommand

Union type of the 9 SDK commands exposed by the React SDK.

type ReactCommand =
  | 'boot'
  | 'shutdown'
  | 'show'
  | 'hide'
  | 'showNewMessage'
  | 'update'
  | 'identify'
  | 'logout'
  | 'getVisitorId';

This is a curated subset of the full SDK command set. Internal and realtime commands (such as sendMessage, connectRealtime, sendTypingIndicator) are intentionally not exposed.

Examples

Drop-in usage

The simplest integration. Add ZicktMessenger once at the root of your app.

import { ZicktMessenger } from '@zickt/react';

export default function App() {
  return (
    <>
      <YourApp />
      <ZicktMessenger
        channelKey="your-channel-key"
        appearance={{ position: 'bottom-right', primaryColor: '#0066CC' }}
        onReady={() => console.log('Widget ready')}
        onUnreadCountChanged={(count) =>
          (document.title = count > 0 ? `(${count}) My App` : 'My App')
        }
      />
    </>
  );
}

Provider and hook

Use ZicktProvider at the root and useZickt in child components to open the widget programmatically.

import { ZicktProvider } from '@zickt/react';

export default function App() {
  return (
    <ZicktProvider channelKey="your-channel-key">
      <YourApp />
    </ZicktProvider>
  );
}

import { useZickt } from '@zickt/react';

export function HelpButton() {
  const { show, isReady } = useZickt();

  return (
    <button onClick={show} disabled={!isReady}>
      Get help
    </button>
  );
}

Identifying a logged-in user

Call identify after the user authenticates to link the visitor session to their account.

import { useEffect } from 'react';
import { useZickt } from '@zickt/react';

export function useAuthSync(user: AuthUser | null) {
  const { isReady, identify, logout } = useZickt();

  useEffect(() => {
    if (!isReady) return;

    if (user) {
      identify({
        id: user.id,
        email: user.email,
        name: user.displayName,
        signedUpAt: user.createdAt,
        custom: { plan: user.plan },
        company: {
          id: user.company.id,
          name: user.company.name,
          plan: user.company.plan,
        },
      });
    } else {
      logout();
    }
  }, [isReady, user, identify, logout]);
}

Custom launcher

Hide the default chat bubble and open the widget from your own UI element.

import { ZicktProvider, useZickt } from '@zickt/react';

function CustomLaunchButton() {
  const { show } = useZickt();
  return <button onClick={show}>Support</button>;
}

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <ZicktProvider channelKey="your-channel-key" hideDefaultLauncher>
      {children}
      <CustomLaunchButton />
    </ZicktProvider>
  );
}

Updating appearance after boot

Pass updated appearance values as a prop or call update directly.

import { useZickt } from '@zickt/react';

export function ThemeSwitch({ isDark }: { isDark: boolean }) {
  const { update } = useZickt();

  useEffect(() => {
    update({ appearance: { theme: isDark ? 'dark' : 'light' } });
  }, [isDark, update]);

  return null;
}

Related