> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scentxp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

## Widget attributes

The `<scentbot-widget>` element is configured through HTML attributes. All attribute names use kebab-case.

## Required attributes

| Attribute    | Type     | Description                                                      |
| ------------ | -------- | ---------------------------------------------------------------- |
| `public-key` | `string` | API key provided by ScentXP. Required for widget initialization. |

## Optional attributes

### Language and user identity

| Attribute  | Type        | Default | Description                                                                                         |
| ---------- | ----------- | ------- | --------------------------------------------------------------------------------------------------- |
| `language` | `string`    | `"en"`  | ISO 639-1 language code (e.g., `"en"`, `"fr"`, `"ar"`). Arabic (`ar`) enables right-to-left layout. |
| `user-id`  | `string`    | `""`    | Identifier for the logged-in user. Used to associate conversations with a specific customer.        |
| `metadata` | JSON string | `"{}"`  | Stringified JSON object with user context. See [Metadata](#metadata) below.                         |

### Positioning and notifications

| Attribute       | Type     | Default          | Description                                                                                                    |
| --------------- | -------- | ---------------- | -------------------------------------------------------------------------------------------------------------- |
| `position`      | `string` | `"bottom-right"` | Widget placement. Options: `bottom-right`, `bottom-left`, `bottom-center`, `center`, `none`, `fill-container`. |
| `notifications` | `string` | —                | Notification style when the widget is closed and receives a message. Options: `popup`, `text`, `number`.       |

### Open/close behavior

| Attribute      | Type                  | Default   | Description                                                                                                                                     |
| -------------- | --------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `default-open` | `"true"` \| `"false"` | —         | Initial state on first page load. Overrides remembered state from previous sessions.                                                            |
| `open`         | `"true"` \| `"false"` | —         | Explicitly controls the widget's open/closed state. When set, overrides user interaction.                                                       |
| `controlled`   | `"true"` \| `"false"` | `"false"` | When `"true"`, the widget's open/close state is fully managed externally via the [`sxp.scentbot.set`](/scentbot/events#control-scentbot) event. |

### Appearance and customization

| Attribute      | Type                  | Default     | Description                                                                                             |
| -------------- | --------------------- | ----------- | ------------------------------------------------------------------------------------------------------- |
| `styles`       | URL string            | —           | URL to a custom CSS file loaded during widget initialization. Use this to override default styles.      |
| `custom-css`   | URL string            | —           | Alias for `styles`.                                                                                     |
| `loading-type` | `string`              | `"default"` | Loading indicator type. Options: `default` (placeholder content), `spinner` (animated spinner).         |
| `buy-info`     | `"true"` \| `"false"` | —           | Show buy button and price information on perfume cards (when available in your catalog).                |
| `disable`      | JSON string           | `"{}"`      | Stringified JSON object to disable specific UI features. See [Disable options](#disable-options) below. |

### Session

| Attribute                       | Type     | Default | Description                                                                                                             |
| ------------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| `chat-history-expiration-hours` | `number` | `12`    | Hours to keep conversation history in the browser. After this period with no user interaction, the conversation resets. |

***

## Metadata

The `metadata` attribute accepts a stringified JSON object with user context that helps ScentBot personalize recommendations:

```html theme={null}
<scentbot-widget
  public-key="your_key"
  language="en"
  metadata='{"brand":"Dior","families":["floral","fresh"],"free_field":"prefers light scents"}'
></scentbot-widget>
```

| Field        | Type       | Description                                  |
| ------------ | ---------- | -------------------------------------------- |
| `brand`      | `string`   | Brand context for scoping the conversation   |
| `families`   | `string[]` | Preferred fragrance families                 |
| `free_field` | `string`   | Free-text context passed to the conversation |

Additional custom fields can be included and will be forwarded to the backend.

***

## Disable options

The `disable` attribute accepts a stringified JSON object. Set any property to `true` to disable that feature:

```html theme={null}
<scentbot-widget
  public-key="your_key"
  language="en"
  disable='{"closeButton":true,"headerAnimation":true}'
></scentbot-widget>
```

| Property          | Description                                                   |
| ----------------- | ------------------------------------------------------------- |
| `closeButton`     | Hide the close button                                         |
| `refreshButton`   | Hide the refresh/reset conversation button                    |
| `header`          | Hide the widget header                                        |
| `headerAnimation` | Disable header animation                                      |
| `openAnimation`   | Disable open/close animation                                  |
| `closeAnimation`  | Disable close animation                                       |
| `perfumeInfo`     | Hide perfume detail information                               |
| `perfumeBuy`      | Hide the buy button on perfume cards                          |
| `perfumePrice`    | Hide price information on perfume cards                       |
| `chatbox`         | Hide the chat input box                                       |
| `background`      | Disable the backdrop overlay                                  |
| `zIndex`          | Disable z-index styling (useful for custom stacking contexts) |

***

## Position modes

| Value            | Behavior                                                                |
| ---------------- | ----------------------------------------------------------------------- |
| `bottom-right`   | Floating button and panel anchored to the bottom-right corner (default) |
| `bottom-left`    | Floating button and panel anchored to the bottom-left corner            |
| `bottom-center`  | Floating button and panel centered at the bottom                        |
| `center`         | Centered on the viewport                                                |
| `fill-container` | Fills the parent container; widget is always open                       |
| `none`           | No positioning styles applied; you control placement with your own CSS  |

<Note>
  When using `fill-container`, the widget opens automatically and fills its parent element. This is useful for embedding ScentBot in a dedicated page section rather than as a floating overlay.
</Note>

## Example: fully configured widget

```html theme={null}
<scentbot-widget
  public-key="pk_live_abc123"
  language="fr"
  user-id="user_42"
  position="bottom-right"
  notifications="popup"
  buy-info="true"
  chat-history-expiration-hours="24"
  metadata='{"brand":"Chanel","families":["oriental","woody"]}'
  disable='{"refreshButton":true}'
></scentbot-widget>
```

## Next steps

<CardGroup cols={2}>
  <Card title="Events" icon="bolt" href="/scentbot/events">
    Listen for add-to-cart events and control the widget programmatically.
  </Card>

  <Card title="Capabilities" icon="wand-magic-sparkles" href="/scentbot/capabilities">
    What ScentBot can do — search types, image search, and more.
  </Card>
</CardGroup>