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

# Configuration reference

> Complete reference for all Obvlo Embed Widget attributes and configuration options.

This page documents every attribute and configuration option available on the `<obvlo-dynamic-content>` custom element. For a step-by-step setup guide, see the [Quick Start](/embed-widget/quick-start).

<Tip>
  Use the [interactive test harness](https://cdn.obvlo.com/widgets/embed-test/index.html) to experiment with these options live — it generates the HTML tag for you in real time.
</Tip>

***

## HTML attributes

These are set directly on the `<obvlo-dynamic-content>` element.

### `host-id` <span style={{color:'#991b1b', background:'#fee2e2', padding:'2px 8px', borderRadius:'4px', fontSize:'0.75rem', fontWeight:600}}>Required</span>

**Type:** `string`

The unique identifier for your host profile. Links the widget to your content in the Obvlo system.

```html theme={null}
<obvlo-dynamic-content host-id="abc123"></obvlo-dynamic-content>
```

<Note>
  In the Obvlo portal, host profiles are listed as **Destinations**. You can find the value for `host-id` in the Destinations table under the **Destination ID** column.
</Note>

***

### `config-id`

**Type:** `string`

Select a specific embedded configuration from your host profile. When omitted, the first configuration in the profile is used.

```html theme={null}
<obvlo-dynamic-content host-id="abc123" config-id="summer-config"></obvlo-dynamic-content>
```

***

### `guide-id`

**Type:** `string`

Display a specific guide when the widget loads. Users can still navigate to other content.

```html theme={null}
<obvlo-dynamic-content host-id="abc123" guide-id="guide-id-123"></obvlo-dynamic-content>
```

***

### `neighbourhood-id`

**Type:** `string`

Display a specific neighbourhood/geographic area when the widget loads.

<Note>
  Only one of `guide-id` or `neighbourhood-id` should be used at a time. If both are provided, `guide-id` takes precedence.
</Note>

***

### `guide-type`

**Type:** `string`

Filter the menu to show only guides of a specific type.

| Value           | Description               |
| --------------- | ------------------------- |
| `guide`         | Standard guides only      |
| `neighbourhood` | Neighbourhood guides only |
| `featured`      | Featured guides only      |

```html theme={null}
<obvlo-dynamic-content host-id="abc123" guide-type="neighbourhood"></obvlo-dynamic-content>
```

***

### `grid-rows`

**Type:** `number` — **Default:** `1`

Number of rows to display in grid views on desktop and tablet devices.

### `grid-rows-mobile`

**Type:** `number` — **Default:** `3`

Number of rows to display in grid views on mobile devices.

```html theme={null}
<obvlo-dynamic-content host-id="abc123" grid-rows="2" grid-rows-mobile="4"></obvlo-dynamic-content>
```

***

### `lang`

**Type:** `string`

Sets the display language for the widget. Must be a BCP 47 language tag supported by your host profile.

| Code    | Language                 |
| ------- | ------------------------ |
| `en-GB` | English (UK) — *default* |
| `en-US` | English (US)             |
| `es-ES` | Spanish (Spain)          |
| `fr-FR` | French (France)          |
| `de-DE` | German (Germany)         |
| `it-IT` | Italian (Italy)          |
| `pt-PT` | Portuguese (Portugal)    |
| `pt-BR` | Portuguese (Brazil)      |
| `zh-CN` | Chinese (Simplified)     |
| `ja-JP` | Japanese                 |
| `ar-SA` | Arabic (Saudi Arabia)    |

See the [Language reference](/reference/language-reference) for all 63 supported languages.

***

### `uid`

**Type:** `string`

Custom user identifier for analytics tracking. If not provided, a random UUID is generated and persisted in browser storage.

```html theme={null}
<obvlo-dynamic-content host-id="abc123" uid="user-12345"></obvlo-dynamic-content>
```

***

### `drawer`

**Type:** `boolean` — **Default:** `false`

Controls whether the widget appears as an overlay drawer or renders inline. This is a boolean attribute — its presence enables drawer mode.

```html theme={null}
<!-- Overlay drawer mode -->
<obvlo-dynamic-content host-id="abc123" drawer></obvlo-dynamic-content>

<!-- Inline mode (default — omit the attribute) -->
<obvlo-dynamic-content host-id="abc123"></obvlo-dynamic-content>
```

### `drawer-delay-ms`

**Type:** `number` — **Default:** `0`

Delay in milliseconds before automatically opening the drawer. Only applies when `drawer` is present.

```html theme={null}
<obvlo-dynamic-content host-id="abc123" drawer drawer-delay-ms="2000"></obvlo-dynamic-content>
```

***

### `disable-just-for-you`

**Type:** `boolean` — **Default:** `false`

Hides the "Just For You" personalised guide from the guide menu. Content personalisation remains fully functional — only the menu entry is hidden.

### `hide-travel`

**Type:** `boolean` — **Default:** `false`

Hides travel-related content categories from the widget.

***

### `geo-location`

**Type:** `string` (JSON object) — **Default:** none

A JSON object containing `lat` and `lng` properties to set the user's geographic location. Used to scope content and enable proximity-based features.

```html theme={null}
<obvlo-dynamic-content
  host-id="abc123"
  geo-location='{"lat":51.505,"lng":-0.09}'>
</obvlo-dynamic-content>
```

<Warning>
  Use single quotes around the `geo-location` value since it contains JSON with double quotes.
</Warning>

### `geo-search-radius`

**Type:** `number` — **Default:** `10000`

Search radius in metres when `geo-location` is set. Controls how far from the provided location the widget will search for content.

```html theme={null}
<obvlo-dynamic-content
  host-id="abc123"
  geo-location='{"lat":51.505,"lng":-0.09}'
  geo-search-radius="5000">
</obvlo-dynamic-content>
```

***

### `config`

**Type:** `string` (JSON object)

An inline JSON string containing an `EmbeddedConfig` object. Use this attribute to pass advanced configuration options directly on the element without relying on a server-side embedded config.

<Note>
  When using `config` in HTML, double quotes inside the JSON must be escaped as `&quot;`. Most frameworks (React, Vue, Angular) handle this automatically when binding to an attribute.
</Note>

```html theme={null}
<obvlo-dynamic-content
  host-id="abc123"
  config="{&quot;modules&quot;:[&quot;Menu&quot;,&quot;Grid&quot;],&quot;kioskMode&quot;:true}">
</obvlo-dynamic-content>
```

See the full [EmbeddedConfig object](#embeddedconfig-object) reference below.

***

## EmbeddedConfig object

The `EmbeddedConfig` object can be passed via the [`config`](#config) HTML attribute or defined in your host profile's embedded configs (managed through the Obvlo portal). All properties are optional — only include the ones you need.

```json theme={null}
{
  "modules": ["Menu", "Grid"],
  "kioskMode": false,
  "requirePreferences": false,
  "disableAnimations": false,
  "disableSavedListings": false,
  "hideGuideHeader": false,
  "hideLanguageSelector": false,
  "preferredTravelMode": "walking",
  "cornerRadius": {
    "card": { "topLeft": 12, "topRight": 12, "bottomLeft": 12, "bottomRight": 12 },
    "button": { "topLeft": 8, "topRight": 8, "bottomLeft": 8, "bottomRight": 8 }
  },
  "containerOptions": {
    "maxWidth": 1240,
    "padding": { "top": 16, "bottom": 16, "left": 16, "right": 16 },
    "map": { "width": "100%", "height": "500px" }
  },
  "customIconUrl": "https://example.com/icon.svg"
}
```

***

### `modules`

**Type:** `string[]`

An ordered array of module names that controls which UI sections the widget displays and in what order. When omitted, the widget uses the default module set from your host profile.

| Module            | Description                                |
| ----------------- | ------------------------------------------ |
| `Banner`          | Hero banner image at the top of the widget |
| `Grid`            | Card grid layout for browsing listings     |
| `List`            | Vertical list layout for listings          |
| `Map`             | Interactive map showing listing locations  |
| `Menu`            | Guide/area navigation menu                 |
| `ListMap`         | Combined list and map split-view           |
| `FunctionalPanel` | Functional actions panel (search, filters) |

The order of modules in the array determines their display order in the widget.

```json theme={null}
{ "modules": ["Menu", "Grid", "Map"] }
```

***

### `kioskMode`

**Type:** `boolean` — **Default:** `false`

Enables kiosk mode, optimised for unattended displays such as hotel lobby screens or tourist information points. Typically combined with `disableAnimations` and `disableSavedListings`.

***

### `requirePreferences`

**Type:** `boolean` — **Default:** `false`

When enabled, the widget prompts users to set their personalisation preferences before showing content. Useful for experiences where personalised results are the primary goal.

***

### `disableAnimations`

**Type:** `boolean` — **Default:** `false`

Disables all transition animations in the widget. Useful for kiosk displays or accessibility requirements.

***

### `disableSavedListings`

**Type:** `boolean` — **Default:** `false`

Hides the saved listings feature, removing save buttons from listing cards and the saved list from the menu.

***

### `hideGuideHeader`

**Type:** `boolean` — **Default:** `false`

Hides the guide header section when a guide is displayed. Useful when embedding in a context that already provides its own header or title.

***

### `hideLanguageSelector`

**Type:** `boolean` — **Default:** `false`

Hides the language selector dropdown from the widget. Use this when the widget language is controlled externally via the [`lang`](#lang) attribute.

***

### `preferredTravelMode`

**Type:** `string` — **Default:** platform default

Sets the preferred travel mode for directions and distance calculations.

| Value     | Description                       |
| --------- | --------------------------------- |
| `driving` | Car/vehicle travel times          |
| `walking` | Walking distances and times       |
| `cycling` | Cycling distances and times       |
| `transit` | Public transport routes and times |

```json theme={null}
{ "preferredTravelMode": "walking" }
```

***

### `cornerRadius`

**Type:** `object`

Customise the border radius of UI elements to match your brand. Each element type accepts an object with `topLeft`, `topRight`, `bottomLeft`, and `bottomRight` values in pixels.

| Property | Description                     |
| -------- | ------------------------------- |
| `card`   | Border radius for content cards |
| `button` | Border radius for buttons       |

```json theme={null}
{
  "cornerRadius": {
    "card": { "topLeft": 16, "topRight": 16, "bottomLeft": 16, "bottomRight": 16 },
    "button": { "topLeft": 24, "topRight": 24, "bottomLeft": 24, "bottomRight": 24 }
  }
}
```

<Tip>
  For uniform corners, set all four values to the same number. Common presets: `0` (square), `8` (small), `12` (medium), `16` (large), `24` (extra-large).
</Tip>

***

### `containerOptions`

**Type:** `object`

Controls the widget container's layout and sizing.

#### `containerOptions.maxWidth`

**Type:** `number` (pixels)

Maximum width of the widget container. The widget will not exceed this width even if the parent element is wider.

#### `containerOptions.padding`

**Type:** `object`

Inner padding of the widget container in pixels.

| Property | Type     | Description              |
| -------- | -------- | ------------------------ |
| `top`    | `number` | Top padding in pixels    |
| `bottom` | `number` | Bottom padding in pixels |
| `left`   | `number` | Left padding in pixels   |
| `right`  | `number` | Right padding in pixels  |

#### `containerOptions.map`

**Type:** `object`

Dimensions for the map module when displayed.

| Property | Type     | Default  | Description                                 |
| -------- | -------- | -------- | ------------------------------------------- |
| `width`  | `string` | `"100%"` | CSS width value (e.g. `"100%"`, `"800px"`)  |
| `height` | `string` | `"auto"` | CSS height value (e.g. `"500px"`, `"60vh"`) |

```json theme={null}
{
  "containerOptions": {
    "maxWidth": 1240,
    "padding": { "top": 20, "bottom": 20, "left": 16, "right": 16 },
    "map": { "width": "100%", "height": "500px" }
  }
}
```

***

### `customIconUrl`

**Type:** `string` (URL)

URL to a custom icon image (SVG recommended) displayed in the widget. Use this to brand the widget with your own logo or icon.

```json theme={null}
{ "customIconUrl": "https://example.com/my-icon.svg" }
```

***

## Configuration priority

When the widget initialises, it merges configuration from multiple sources. A value from a higher-priority source always wins.

| Priority    | Source                      | Description                                                          |
| ----------- | --------------------------- | -------------------------------------------------------------------- |
| 1 — highest | **HTML attributes**         | Values set directly on the element, including the `config` attribute |
| 2           | **Named embedded config**   | The embedded config matching `config-id`, if provided                |
| 3           | **Default embedded config** | The first embedded config in your host profile                       |
| 4 — lowest  | **Attribute defaults**      | Default values documented on this page                               |

***

## Full examples

### Modular menu with grid

```html theme={null}
<obvlo-dynamic-content
  host-id="abc123"
  grid-rows="2"
  config="{&quot;modules&quot;:[&quot;Menu&quot;,&quot;Grid&quot;]}">
</obvlo-dynamic-content>
```

### Kiosk display

```html theme={null}
<obvlo-dynamic-content
  host-id="abc123"
  disable-just-for-you
  config="{&quot;modules&quot;:[&quot;Menu&quot;,&quot;Grid&quot;],&quot;kioskMode&quot;:true,&quot;disableAnimations&quot;:true,&quot;disableSavedListings&quot;:true}">
</obvlo-dynamic-content>
```

### Geo-scoped with map

```html theme={null}
<obvlo-dynamic-content
  host-id="abc123"
  geo-location='{"lat":48.8566,"lng":2.3522}'
  geo-search-radius="5000"
  config="{&quot;modules&quot;:[&quot;Menu&quot;,&quot;Map&quot;]}">
</obvlo-dynamic-content>
```

### Custom-branded with rounded cards

```html theme={null}
<obvlo-dynamic-content
  host-id="abc123"
  hide-travel
  config="{&quot;modules&quot;:[&quot;Menu&quot;,&quot;Grid&quot;],&quot;hideLanguageSelector&quot;:true,&quot;cornerRadius&quot;:{&quot;card&quot;:{&quot;topLeft&quot;:16,&quot;topRight&quot;:16,&quot;bottomLeft&quot;:16,&quot;bottomRight&quot;:16}},&quot;customIconUrl&quot;:&quot;https://example.com/icon.svg&quot;}">
</obvlo-dynamic-content>
```

### Drawer with delayed auto-open

```html theme={null}
<obvlo-dynamic-content
  host-id="abc123"
  drawer
  drawer-delay-ms="3000"
  lang="fr-FR">
</obvlo-dynamic-content>
```

***

## Related pages

* [Developers overview](/developer-docs/overview)
* [Quick Start](/embed-widget/quick-start)
* [Language reference](/reference/language-reference)