> For the complete documentation index, see [llms.txt](https://alhena.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://alhena.gitbook.io/docs/developer-reference/website-sdk/styles-api.md).

# Styles API

The Alhena Widget SDK provides extensive styling options to customize the chat widget's appearance, positioning, and behavior to match your website's design.

## Overview

You can configure widget styles in two ways:

1. **Initial configuration** - Set styles when the widget loads via `document.gleenConfig.styles`
2. **Dynamic updates** - Change styles at runtime using `window.gleenWidget.setStyles()`

***

## Quick Reference

| Property                       | Type    | Default   | Description                                          |
| ------------------------------ | ------- | --------- | ---------------------------------------------------- |
| `widget_position`              | string  | `'RIGHT'` | Widget placement: `'RIGHT'`, `'LEFT'`, or `'CENTER'` |
| `bottom_spacing`               | number  | `0`       | Distance from bottom of viewport (px)                |
| `left_spacing`                 | number  | `0`       | Distance from left edge (px)                         |
| `right_spacing`                | number  | `0`       | Distance from right edge (px)                        |
| `mobile_bottom_spacing`        | number  | `0`       | Bottom spacing on mobile (px)                        |
| `mobile_left_spacing`          | number  | `0`       | Left spacing on mobile (px)                          |
| `mobile_right_spacing`         | number  | `0`       | Right spacing on mobile (px)                         |
| `use_same_position_for_mobile` | boolean | `false`   | Use desktop spacing on mobile                        |
| `widget_border_radius`         | number  | `0`       | Border radius of chat window (px)                    |
| `widget_width`                 | number  | `0`       | Width of chat window (px)                            |
| `widget_background_color`      | string  | `'#fff'`  | Background color (CSS color)                         |
| `z_index`                      | number  | `200000`  | Z-index for chat window                              |
| `launcher_z_index`             | number  | `200000`  | Z-index for launcher button                          |
| `fontFamily`                   | string  | (auto)    | Custom font family                                   |

***

## setStyles(styles)

Dynamically updates the widget's visual appearance and positioning after initialization. The provided styles are merged with existing configuration.

```javascript
window.gleenWidget.setStyles({
    widget_position: 'LEFT',
    bottom_spacing: 20,
    left_spacing: 20
});
```

***

## Style Properties

### Positioning

Control where the widget appears on the page.

#### widget\_position

Sets the horizontal placement of the widget.

| Value      | Description                               |
| ---------- | ----------------------------------------- |
| `'RIGHT'`  | Aligns widget to the right side (default) |
| `'LEFT'`   | Aligns widget to the left side            |
| `'CENTER'` | Centers the widget horizontally           |

```javascript
window.gleenWidget.setStyles({
    widget_position: 'LEFT'
});
```

#### bottom\_spacing

Distance in pixels from the bottom of the viewport. Use this to position the widget above other fixed elements like cookie banners.

```javascript
window.gleenWidget.setStyles({
    bottom_spacing: 80 // 80px from bottom
});
```

#### left\_spacing

Distance in pixels from the left edge of the viewport. Only applies when `widget_position` is `'LEFT'`.

```javascript
window.gleenWidget.setStyles({
    widget_position: 'LEFT',
    left_spacing: 20
});
```

#### right\_spacing

Distance in pixels from the right edge of the viewport. Only applies when `widget_position` is `'RIGHT'`.

```javascript
window.gleenWidget.setStyles({
    widget_position: 'RIGHT',
    right_spacing: 20
});
```

***

### Mobile-Specific Positioning

Override positioning values specifically for mobile devices.

#### mobile\_bottom\_spacing

Bottom spacing override for mobile devices. Useful for avoiding overlap with mobile navigation bars.

```javascript
window.gleenWidget.setStyles({
    bottom_spacing: 20,
    mobile_bottom_spacing: 80 // More space on mobile
});
```

#### mobile\_left\_spacing

Left spacing override for mobile devices.

```javascript
window.gleenWidget.setStyles({
    widget_position: 'LEFT',
    left_spacing: 20,
    mobile_left_spacing: 10
});
```

#### mobile\_right\_spacing

Right spacing override for mobile devices.

```javascript
window.gleenWidget.setStyles({
    widget_position: 'RIGHT',
    right_spacing: 20,
    mobile_right_spacing: 10
});
```

#### use\_same\_position\_for\_mobile

When `true`, uses desktop spacing values on mobile instead of mobile-specific overrides.

```javascript
window.gleenWidget.setStyles({
    bottom_spacing: 20,
    right_spacing: 20,
    use_same_position_for_mobile: true // Same spacing on all devices
});
```

***

### Visual Styling

Customize the widget's appearance.

#### widget\_border\_radius

Border radius of the chat window in pixels. Use this to match your site's design language.

```javascript
window.gleenWidget.setStyles({
    widget_border_radius: 16 // Rounded corners
});
```

#### widget\_width

Width of the chat window in pixels. When set to `0`, uses the default width.

```javascript
window.gleenWidget.setStyles({
    widget_width: 400 // 400px wide
});
```

#### widget\_background\_color

Background color of the chat window. Accepts any valid CSS color value.

```javascript
window.gleenWidget.setStyles({
    widget_background_color: '#f5f5f5'
});

// Or with rgba for transparency
window.gleenWidget.setStyles({
    widget_background_color: 'rgba(255, 255, 255, 0.95)'
});
```

***

### Layering (Z-Index)

Control the stacking order of widget elements.

#### z\_index

Z-index for the chat window. Increase this if the widget appears behind other elements.

```javascript
window.gleenWidget.setStyles({
    z_index: 999999
});
```

#### launcher\_z\_index

Z-index specifically for the launcher button. Falls back to `z_index` if not specified.

```javascript
window.gleenWidget.setStyles({
    z_index: 200000,
    launcher_z_index: 300000 // Launcher on top
});
```

***

### Typography

Customize the widget's fonts.

#### fontFamily

Custom font family for the chat widget. Accepts any valid CSS `font-family` value.

{% hint style="warning" %}
The SDK does not load fonts. You must ensure the font is loaded by your website before specifying it here.
{% endhint %}

```javascript
window.gleenWidget.setStyles({
    fontFamily: 'Inter, system-ui, sans-serif'
});
```

If not specified, the widget uses:

1. Your organization's configured font (from dashboard settings)
2. Falls back to `'Nunito, sans-serif'`

***

## Initial Configuration

Set styles during initialization by including them in `document.gleenConfig.styles`:

```javascript
document.gleenConfig = {
    company: 'your-company-key',
    apiBaseUrl: 'https://app.alhena.ai',
    styles: {
        widget_position: 'RIGHT',
        bottom_spacing: 20,
        right_spacing: 20,
        widget_border_radius: 12,
        fontFamily: 'Inter, sans-serif'
    }
};
```

This is useful for overriding dashboard settings on specific pages.

***

## Dynamic Updates

Update styles at runtime using `setStyles()`. Styles are merged with existing values:

```javascript
// Initial positioning
window.gleenWidget.setStyles({
    widget_position: 'RIGHT',
    right_spacing: 20
});

// Later, adjust for mobile
function adjustForMobile() {
    window.gleenWidget.setStyles({
        bottom_spacing: 80,
        right_spacing: 10
    });
}

// Respond to viewport changes
window.addEventListener('resize', function() {
    if (window.innerWidth < 768) {
        adjustForMobile();
    }
});
```

***

## Complete Example

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Styled Chat Widget</title>
    <!-- Load your custom font -->
    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap" rel="stylesheet">
</head>
<body>

<!-- Alhena SDK with custom styles -->
<script>
document.gleenConfig = {
    company: 'your-company-key',
    apiBaseUrl: 'https://app.alhena.ai',
    styles: {
        // Position bottom-right with spacing
        widget_position: 'RIGHT',
        bottom_spacing: 20,
        right_spacing: 20,

        // Mobile-specific adjustments
        mobile_bottom_spacing: 80,
        mobile_right_spacing: 10,

        // Visual styling
        widget_border_radius: 16,
        widget_width: 380,
        widget_background_color: '#ffffff',

        // Ensure visibility over other elements
        z_index: 999999,

        // Typography
        fontFamily: 'Inter, sans-serif'
    }
};
</script>
<script src="https://app.alhena.ai/sdk/gleenWidget.js"></script>

<!-- Dynamic style updates -->
<script>
// Show cookie banner - push widget up
document.getElementById('accept-cookies').addEventListener('click', function() {
    document.getElementById('cookie-banner').style.display = 'none';
    window.gleenWidget.setStyles({
        bottom_spacing: 20,
        mobile_bottom_spacing: 20
    });
});

// Cookie banner visible - more spacing needed
if (document.getElementById('cookie-banner')) {
    window.gleenWidget.setStyles({
        bottom_spacing: 100,
        mobile_bottom_spacing: 120
    });
}
</script>

</body>
</html>
```

***

## Common Use Cases

### Avoid Overlap with Cookie Banner

```javascript
// When cookie banner is shown
window.gleenWidget.setStyles({
    bottom_spacing: 100
});

// When cookie banner is dismissed
window.gleenWidget.setStyles({
    bottom_spacing: 20
});
```

### Match Brand Design

```javascript
window.gleenWidget.setStyles({
    widget_border_radius: 0,  // Sharp corners
    widget_background_color: '#1a1a2e',
    fontFamily: 'YourBrandFont, sans-serif'
});
```

### Mobile-Optimized Layout

```javascript
window.gleenWidget.setStyles({
    widget_position: 'RIGHT',
    right_spacing: 16,
    bottom_spacing: 16,
    mobile_right_spacing: 8,
    mobile_bottom_spacing: 70  // Account for mobile nav
});
```

### Ensure Widget Visibility

```javascript
// Widget hidden behind modal or overlay
window.gleenWidget.setStyles({
    z_index: 2147483647  // Maximum z-index
});
```

***

## Related Resources

* [JavaScript API](/docs/developer-reference/website-sdk/javascript-api.md) - Complete method reference
* [Custom Data](/docs/developer-reference/website-sdk/custom-data.md) - Passing user data to the widget
* [Examples](/docs/developer-reference/website-sdk/examples.md) - Code examples for common use cases