Styling

CSS Variables

The widget uses CSS variables for easy theming. Override these in your CSS:

:root {
  /* Colors */
  --opencx-primary-color: #007bff;
  --opencx-secondary-color: #6c757d;
  --opencx-background-color: #ffffff;
  --opencx-text-color: #212529;
  
  /* Typography */
  --opencx-font-family: system-ui, -apple-system, sans-serif;
  --opencx-font-size: 16px;
  
  /* Spacing */
  --opencx-spacing-sm: 0.5rem;
  --opencx-spacing-md: 1rem;
  --opencx-spacing-lg: 1.5rem;
  
  /* Border Radius */
  --opencx-border-radius: 8px;
}

Custom CSS Classes

Target these classes to customize specific components:

/* Chat container */
.opencx-widget-container {
  /* Your styles */
}

/* Message bubbles */
.opencx-message-bubble {
  /* Your styles */
}

/* User message */
.opencx-user-message {
  /* Your styles */
}

/* Bot message */
.opencx-bot-message {
  /* Your styles */
}

/* Input area */
.opencx-input-container {
  /* Your styles */
}

Behavior Customization

Message Display

Customize how messages are rendered:

import { createChat } from '@opencx/widget';

const chat = createChat({
  // ... other options
  messageRenderer: (message) => {
    if (message.type === 'FROM_BOT') {
      return {
        // Custom rendering logic
        element: customRenderFunction(message)
      };
    }
    return defaultRenderer(message);
  }
});

Input Validation

Add custom input validation:

const chat = createChat({
  // ... other options
  inputValidation: (message) => {
    if (message.length < 2) {
      return {
        isValid: false,
        error: 'Message too short'
      };
    }
    return { isValid: true };
  }
});

Advanced Customization

Custom Components (React)

Create your own components while using our hooks:

import { useChat, useConfigData } from '@opencx/widget/react';

function CustomChatInterface() {
  const { messages, sendMessage } = useChat();
  const { config } = useConfigData();
  
  return (
    <div className="custom-chat">
      {messages.map((msg) => (
        <CustomMessageBubble
          key={msg.id}
          message={msg}
        />
      ))}
      <CustomInputArea onSend={sendMessage} />
    </div>
  );
}

Platform Integration

Customize platform-specific behavior:

const customPlatform = {
  env: {
    platform: 'web',
    // Add custom environment variables
    customFeature: true
  },
  storage: {
    // Custom storage implementation
    getItem: async (key) => {
      // Your custom storage logic
    },
    setItem: async (key, value) => {
      // Your custom storage logic
    }
  },
  logger: {
    // Custom logging implementation
    debug: (msg) => {
      // Your custom logging logic
    },
    error: (msg) => {
      // Your custom error logging
    }
  }
};

const chat = createChat({
  // ... other options
  platform: customPlatform
});

Event Handling

Subscribe to specific events:

chat.on('message:sent', (message) => {
  // Custom handling of sent messages
});

chat.on('message:received', (message) => {
  // Custom handling of received messages
});

chat.on('error', (error) => {
  // Custom error handling
});

Best Practices

  1. Maintain Accessibility

    • Keep color contrast ratios WCAG compliant
    • Ensure keyboard navigation works
    • Add proper ARIA labels
  2. Responsive Design

    • Use relative units (rem, em) for sizing
    • Test on different screen sizes
    • Implement mobile-first design
  3. Performance

    • Minimize custom CSS overrides
    • Use efficient event handlers
    • Implement proper cleanup in custom components
  4. Branding

    • Keep customizations consistent with your brand
    • Test changes across different themes
    • Document custom styles for team reference