UI Customization

The ArctenAgent component offers extensive customization options to match your application's design and user experience.

Theme

Control the visual theme of the agent.

<ArctenAgent theme="dark" />

Options:

• "light" - Light theme
• "dark" - Dark theme
• "auto" - Follows system preference (default)

Title

Customize the header title.

<ArctenAgent title="Support Assistant" />

Default: "Chat"

Logo

Add a custom logo to the empty state.

<ArctenAgent
  logo={<img src="/logo.png" alt="Logo" className="w-12 h-12" />}
/>

You can use any React element:

import { Sparkles } from "lucide-react";

<ArctenAgent
  logo={
    <div className="flex items-center gap-2">
      <Sparkles className="w-8 h-8 text-blue-500" />
      <span className="text-lg font-bold">AI Helper</span>
    </div>
  }
/>

Initial State

Control whether the sidebar is expanded on load.

<ArctenAgent initiallyExpanded={true} />

Default: false

Dimensions

Customize the sidebar width.

<ArctenAgent
  defaultWidth={450}
  minWidth={320}
  maxWidth={900}
/>

Defaults:

• defaultWidth: 384px
• minWidth: 300px
• maxWidth: 800px

Animations

Enable or disable animations.

<ArctenAgent animated={false} />

Default: true

When disabled, the agent will render without motion effects, which can improve performance on lower-end devices.

Layout

Set the layout style.

<ArctenAgent layout="sidebar" />

Options:

• "sidebar" - Sidebar layout (default and currently only supported option)

Complete Customization Example

import { ArctenAgent } from "@arcteninc/core";
import "@arcteninc/core/styles";
import { Bot } from "lucide-react";

export default function CustomAgent() {
  return (
    <ArctenAgent
      // Visual
      theme="dark"
      title="AI Assistant"
      logo={<Bot className="w-10 h-10 text-purple-500" />}

      // Dimensions
      defaultWidth={450}
      minWidth={350}
      maxWidth={700}

      // Behavior
      initiallyExpanded={true}
      animated={true}

      // Content
      systemPrompt="You are a helpful AI assistant."
    />
  );
}

Styling Integration

The agent uses Tailwind CSS and respects your application's theme. It automatically adapts to dark mode when theme="auto" is set.

Custom Styles

You can wrap the agent in a container with custom styles:

<div className="border-l-4 border-blue-500">
  <ArctenAgent
    title="Custom Styled Agent"
    theme="auto"
  />
</div>

CSS Variables

The agent component uses CSS variables that you can override in your global styles:

/* Example: Customize colors */
#arcten-sidebar {
  --border-color: #e5e7eb;
  --background: #ffffff;
}

#arcten-sidebar[data-theme="dark"] {
  --border-color: #374151;
  --background: #1f2937;
}

Responsive Behavior

The agent automatically handles responsive layouts:

• Desktop: Resizable sidebar with drag handle
• Mobile: Full-width overlay when expanded
• Detached Mode: Floating window that can be dragged and resized

Detach/Dock Controls

Users can detach the agent into a floating window or dock it back to the sidebar using the built-in controls in the header. This state persists over reloads.

Best Practices

Theme Selection

• Use "auto" for the best user experience (respects system preferences)
• Use "light" or "dark" when you want to match a specific app theme

Dimensions

• Keep defaultWidth between 350-500px for optimal readability
• Ensure minWidth is at least 300px to avoid cramped UI
• Set maxWidth to prevent the agent from taking too much screen space

Initial State

• Set initiallyExpanded={false} for focused applications where the agent is supplementary
• Set initiallyExpanded={true} for agent-first applications

Logo

• Keep logos small (40-60px) to fit well in the empty state
• Use SVGs for crisp rendering at all sizes
• Consider adding a subtle animation to draw attention

Animations

• Keep animated={true} for modern applications
• Disable animations for accessibility or performance concerns
• Test on lower-end devices if you have a broad user base