> For the complete documentation index, see [llms.txt](https://docs.meganova.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.meganova.ai/character-studio/embed-widgets/customization.md).

# Customization

> **Note:** Customize every aspect of your embed widget. Match your brand, configure behavior, and optimize the user experience.

## Overview

Customize your embed:

* **Appearance** — Colors, fonts, layout
* **Behavior** — Interactions, memory, voice
* **Branding** — Logo, messages, style
* **Integration** — Callbacks, events, API

## Appearance Options

### Theme

#### Built-in Themes

| Theme | Description                 |
| ----- | --------------------------- |
| Light | White/light gray background |
| Dark  | Dark gray/black background  |
| Auto  | Matches system preference   |

#### Custom Colors

```javascript
MegaNova.init({
  theme: {
    primary: '#6366f1',
    background: '#ffffff',
    text: '#1f2937',
    userBubble: '#6366f1',
    botBubble: '#f3f4f6'
  }
});
```

### Typography

#### Font Selection

```javascript
fontFamily: 'Inter, system-ui, sans-serif'
```

#### Font Sizes

| Element  | Default |
| -------- | ------- |
| Messages | 14px    |
| Name     | 16px    |
| Input    | 14px    |

### Layout

#### Dimensions

```javascript
width: 400,      // pixels or '100%'
height: 600,     // pixels or '100%'
maxHeight: 800   // maximum height
```

#### Border & Shadow

```javascript
borderRadius: 12,
boxShadow: '0 4px 6px rgba(0,0,0,0.1)'
```

### Avatar

#### Display Options

```javascript
avatar: {
  show: true,
  size: 40,
  borderRadius: '50%'
}
```

#### Custom Avatar

```javascript
avatar: {
  show: true,
  customUrl: 'https://yoursite.com/avatar.png'
}
```

## Behavior Options

### Voice

#### Enable Voice

```javascript
voice: {
  enabled: true,
  autoPlay: false,
  rate: 1.0,
  pitch: 1.0
}
```

### Typing Indicator

```javascript
typing: {
  enabled: true,
  delay: 500,      // ms before showing
  minDuration: 800 // minimum display time
}
```

### Memory

#### Session Memory

```javascript
memory: 'session'  // resets on page refresh
```

#### Persistent Memory

```javascript
memory: 'persistent'  // remembers across visits
```

### Input Options

```javascript
input: {
  placeholder: 'Type a message...',
  maxLength: 1000,
  submitOnEnter: true
}
```

## Branding

### Custom Welcome

```javascript
welcome: {
  message: 'Hello! How can I help you today?',
  showAvatar: true
}
```

### Powered By

```javascript
branding: {
  showPoweredBy: true,  // Shows "Powered by MegaNova"
  customText: null       // Override text
}
```

### Custom Header

```javascript
header: {
  title: 'Support Chat',
  subtitle: 'We usually reply instantly',
  showClose: true
}
```

## Advanced Configuration

### Callbacks

#### On Message

```javascript
onMessage: (message) => {
  console.log('New message:', message);
}
```

#### On Ready

```javascript
onReady: () => {
  console.log('Chat widget loaded');
}
```

#### On Error

```javascript
onError: (error) => {
  console.error('Chat error:', error);
}
```

### Events

Listen for events:

```javascript
const widget = MegaNova.init({...});

widget.on('message', (data) => {
  // Handle new message
});

widget.on('open', () => {
  // Widget opened
});

widget.on('close', () => {
  // Widget closed
});
```

### API Methods

Control programmatically:

```javascript
// Send message
widget.sendMessage('Hello!');

// Open widget
widget.open();

// Close widget
widget.close();

// Clear history
widget.clearHistory();

// Get conversation
widget.getConversation();
```

## Full Configuration Example

```javascript
MegaNova.init({
  container: 'chat-widget',
  characterId: 'abc123',

  // Appearance
  theme: 'dark',
  width: 380,
  height: 600,
  borderRadius: 16,

  // Colors
  colors: {
    primary: '#6366f1',
    background: '#1f2937',
    text: '#f9fafb'
  },

  // Typography
  fontFamily: 'Inter, sans-serif',

  // Avatar
  avatar: {
    show: true,
    size: 36
  },

  // Behavior
  voice: {
    enabled: false
  },
  typing: {
    enabled: true,
    delay: 300
  },
  memory: 'persistent',

  // Branding
  header: {
    title: 'Chat with Luna',
    subtitle: 'AI Assistant'
  },
  welcome: {
    message: 'Hi there! I\'m Luna. How can I help?'
  },
  branding: {
    showPoweredBy: true
  },

  // Input
  input: {
    placeholder: 'Ask me anything...',
    maxLength: 500
  },

  // Access
  safeMode: true,

  // Callbacks
  onReady: () => console.log('Ready'),
  onMessage: (msg) => console.log('Message:', msg),
  onError: (err) => console.error('Error:', err)
});
```

## Mobile Optimization

### Responsive Design

```javascript
responsive: true,
mobileBreakpoint: 768,
mobileFullscreen: true
```

### Touch Optimization

```javascript
touch: {
  enabled: true,
  swipeToClose: true
}
```

## Performance

### Lazy Loading

```javascript
lazyLoad: true,
loadOnVisible: true
```

### Caching

```javascript
cache: {
  enabled: true,
  duration: 3600  // seconds
}
```

## See Also

* [Creating Embeds](https://docs.meganova.ai/character-studio/embed-widgets/creating-embeds.md) — Basic setup
* [Embed Overview](https://docs.meganova.ai/character-studio/embed-widgets.md) — Introduction
* [API Integration](https://docs.meganova.ai/character-studio/advanced/api-integration.md) — Advanced usage
