@channlize/react

React components and hooks for the Channlize platform. Build customer support experiences that route directly to Slack.

Installation

npm install @channlize/react

Note: This package has peer dependencies on react and react-dom (>=16.8.0).

Quick Start (Plug & Play)

The easiest way to add live chat to your React app:

import { ChannlizeChat } from '@channlize/react';

function App() {
  return (
    <div>
      <YourAppContent />
      
      {/* That's it! Floating chat widget with everything included */}
      <ChannlizeChat
        config={{
          apiKey: 'your-widget-key',
          projectId: 'your-project-id',
        }}
        position="bottom-right"
        chatProps={{
          title: "Customer Support",
          placeholder: "How can we help you today?"
        }}
      />
    </div>
  );
}

The ChannlizeChat component includes:

• ✅ Provider (no need to wrap your app)
• ✅ Floating button with customizable position
• ✅ Chat window with real-time messaging
• ✅ Animations and responsive design
• ✅ Extensive styling options

Advanced Usage

For more control, use the individual components:

Manual Setup

Wrap your app with the ChannlizeProvider:

import { ChannlizeProvider } from '@channlize/react';

function App() {
  return (
    <ChannlizeProvider
      config={{
        apiKey: 'your-api-key',
        projectId: 'your-project-id',
      }}
    >
      <YourAppContent />
    </ChannlizeProvider>
  );
}

Contact Form Component

import { ContactForm } from '@channlize/react';

function ContactPage() {
  return (
    <ContactForm
      onSuccess={() => alert('Message sent!')}
      onError={(error) => console.error(error)}
      customFields={[
        {
          name: 'department',
          label: 'Department',
          type: 'select',
          required: true,
          options: ['Sales', 'Support', 'Billing'],
        },
        {
          name: 'priority',
          label: 'Priority',
          type: 'select',
          options: ['Low', 'Medium', 'High'],
        },
      ]}
      styles={{
        form: { maxWidth: '500px' },
        button: { background: '#007bff', color: 'white' },
      }}
    />
  );
}

Support Chat Component

import { SupportChat } from '@channlize/react';

function SupportPage() {
  return (
    <SupportChat
      autoStart={true}
      title="Customer Support"
      placeholder="How can we help you?"
      onMessage={(message) => {
        console.log('New message:', message);
      }}
      styles={{
        container: { 
          width: '400px', 
          height: '500px',
          border: '1px solid #ccc',
          borderRadius: '8px',
        },
        header: { 
          background: '#007bff', 
          color: 'white' 
        },
      }}
    />
  );
}

Custom Hook Usage

useContactForm

import { useContactForm } from '@channlize/react';

function CustomContactForm() {
  const { submit, isSubmitting, isSuccess, error, reset } = useContactForm({
    onSuccess: (response) => {
      console.log('Form submitted:', response);
    },
    onError: (error) => {
      console.error('Submission failed:', error);
    },
  });

  const handleSubmit = async (e) => {
    e.preventDefault();
    await submit({
      name: 'John Doe',
      email: '[email protected]',
      message: 'Hello!',
    });
  };

  if (isSuccess) {
    return (
      <div>
        <p>Thank you! Your message has been sent.</p>
        <button onClick={reset}>Send another message</button>
      </div>
    );
  }

  return (
    <form onSubmit={handleSubmit}>
      {/* Your form fields */}
      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? 'Sending...' : 'Send'}
      </button>
      {error && <p>Error: {error.message}</p>}
    </form>
  );
}

useChatSession

import { useChatSession } from '@channlize/react';

function CustomChat() {
  const {
    session,
    messages,
    isConnecting,
    isConnected,
    error,
    sendMessage,
    startSession,
    endSession,
  } = useChatSession({
    autoConnect: false,
    metadata: { page: 'support' },
    onMessage: (message) => {
      console.log('New message:', message);
    },
  });

  const handleSendMessage = async () => {
    await sendMessage('Hello from custom chat!');
  };

  if (!session) {
    return (
      <div>
        <button onClick={startSession} disabled={isConnecting}>
          {isConnecting ? 'Connecting...' : 'Start Chat'}
        </button>
      </div>
    );
  }

  return (
    <div>
      <div>Status: {isConnected ? 'Connected' : 'Disconnected'}</div>
      <div>
        {messages.map((message) => (
          <div key={message.id}>
            <strong>{message.author}:</strong> {message.content}
          </div>
        ))}
      </div>
      <button onClick={handleSendMessage}>Send Message</button>
      <button onClick={endSession}>End Chat</button>
      {error && <div>Error: {error.message}</div>}
    </div>
  );
}

Components

ChannlizeChat (Recommended)

All-in-one floating chat widget - The easiest way to add live chat to any React app. Includes provider, button, and chat window.

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | config | ChannlizeConfig | required | API configuration (apiKey, projectId, baseUrl) | | position | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' | 'bottom-right' | Position of the floating button | | offset | { x?: number; y?: number } | { x: 24, y: 24 } | Offset from edges in pixels | | buttonElement | ReactNode | - | Custom button (overrides default) | | buttonIcon | ReactNode | - | Custom icon (used if buttonElement not provided) | | buttonSize | number | 56 | Button size in pixels | | buttonColors | { background?: string; hover?: string; text?: string } | Blue gradient | Button colors | | chatProps | SupportChatProps | {} | Props passed to internal SupportChat component | | defaultOpen | boolean | false | Whether to start open | | showBadge | boolean | false | Whether to show unread count badge | | unreadCount | number | 0 | Unread message count | | zIndex | number | 1000 | CSS z-index | | showOnMobile | boolean | true | Whether to show on mobile devices | | onOpen | () => void | - | Callback when chat opens | | onClose | () => void | - | Callback when chat closes | | enableAnimations | boolean | true | Enable smooth animations | | buttonClassName | string | '' | Custom class for button container | | chatClassName | string | '' | Custom class for chat container |

Examples:

// Minimal setup
<ChannlizeChat
  config={{
    apiKey: 'your-widget-key',
    projectId: 'your-project-id',
  }}
/>

// Custom positioning and colors
<ChannlizeChat
  config={{ apiKey: 'key', projectId: 'id' }}
  position="bottom-left"
  offset={{ x: 16, y: 80 }}
  buttonColors={{
    background: '#10b981',
    hover: '#059669',
    text: '#ffffff',
  }}
/>

// With custom chat options
<ChannlizeChat
  config={{ apiKey: 'key', projectId: 'id' }}
  chatProps={{
    title: "24/7 Support",
    placeholder: "Ask us anything...",
    showTimestamps: true,
    styles: {
      header: {
        background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
      },
    },
  }}
/>

// With unread badge
<ChannlizeChat
  config={{ apiKey: 'key', projectId: 'id' }}
  showBadge={true}
  unreadCount={3}
  onOpen={() => console.log('Chat opened')}
/>

// Custom button
<ChannlizeChat
  config={{ apiKey: 'key', projectId: 'id' }}
  buttonElement={
    <div style={{ 
      padding: '12px 24px',
      background: '#000',
      color: '#fff',
      borderRadius: '8px',
      cursor: 'pointer',
    }}>
      Need Help? 💬
    </div>
  }
/>

ContactForm

A complete contact form component with validation and submission handling.

Props:

• customFields?: Array<CustomField> - Additional form fields
• onSuccess?: () => void - Success callback
• onError?: (error: Error) => void - Error callback
• className?: string - CSS class name
• styles?: ContactFormStyles - Custom styles object
• submitText?: string - Submit button text
• successMessage?: string - Success message text

SupportChat

A real-time chat widget with message history and file attachments.

Props:

• autoStart?: boolean - Auto-start chat session
• metadata?: Record<string, unknown> - Session metadata
• onMessage?: (message: ChatMessage) => void - New message callback
• onError?: (error: Error) => void - Error callback
• className?: string - CSS class name
• styles?: SupportChatStyles - Custom styles object
• title?: string - Chat header title
• placeholder?: string - Input placeholder text
• maxHeight?: string - Maximum container height

Hooks

useContactForm

Hook for managing contact form submission state.

Options:

• onSuccess?: (response: CreateContactResponse) => void
• onError?: (error: ChannlizeError) => void

Returns:

• submit: (data: ContactFormData) => Promise<void>
• isSubmitting: boolean
• isSuccess: boolean
• error: ChannlizeError | null
• reset: () => void

useChatSession

Hook for managing chat sessions with real-time messaging.

Options:

• autoConnect?: boolean
• metadata?: Record<string, unknown>
• onMessage?: (message: ChatMessage) => void
• onError?: (error: ChannlizeError) => void

Returns:

• session: ChatSession | null
• messages: ChatMessage[]
• isConnecting: boolean
• isConnected: boolean
• error: ChannlizeError | null
• sendMessage: (content: string, attachments?: File[]) => Promise<void>
• startSession: () => Promise<void>
• endSession: () => Promise<void>

Styling

All components accept a styles prop for custom styling. You can also use CSS classes with the className prop. Components use semantic class names prefixed with channlize-.

CSS Classes

• .channlize-contact-form
• .channlize-contact-form-success
• .channlize-field
• .channlize-error
• .channlize-chat-container
• .channlize-chat-header
• .channlize-chat-messages
• .channlize-message
• .channlize-message-user
• .channlize-message-agent
• .channlize-chat-input-container

TypeScript

This package is written in TypeScript and includes full type definitions. All components, hooks, and utilities are fully typed.

License

MIT