# Bottom Bar

Show a bottom-docked input with conversation starters that hand off to the full agent.

The Bottom Bar is a single-line input docked bottom-center of the page, with conversation starters above it. It is disabled by default and does not render while the agent is open.

Starters come from [conversation starters](/customize/conversation-starters/). Override them at runtime with `setConversationStarters`.

## Settings

| Field | Default | Meaning |
| :--- | :--- | :--- |
| `enabled` | `false` | Master gate for the feature. The Bottom Bar renders only when this is the literal boolean `true`. Any other value (including omitted) keeps it off. |
| `maxVisibleStarters` | `5` | How many conversation starters are shown in the bar at once. Capped at 5. On small screens the SDK shows at most 3 — this mobile cap is not configurable. |
| `reopenFrequency` | `"EVERY_LOAD"` | Controls when the bar may appear again **after the user chooses Turn off bottom bar**. Does not affect normal agent open/close — the bar returns when the agent closes unless the user explicitly dismissed it. `"EVERY_LOAD"` — next page load only, nothing persisted. `"NEVER"` — never again in this browser. `"AFTER_DAYS"` — again after `reopenFrequencyDays` days. |
| `reopenFrequencyDays` | `30` | Days to wait before showing the bar again when `reopenFrequency` is `"AFTER_DAYS"`. Minimum `1`. Ignored for other values of `reopenFrequency`. |
| `starterClickBehavior` | `"OPEN_AGENT"` | What happens when the user clicks a starter. `"OPEN_AGENT"` — open the full agent and send the starter text immediately. `"FILL_INPUT"` — type the starter into the bar input so the user can edit before submitting. Submitting from the input always opens the agent. |
| `idleTimeoutMs` | `5000` | In `FULL` mode, collapse to `COMPACT` after this many milliseconds without interaction. Set to `0` to disable auto-compact. Values greater than `0` are clamped to at least `2000`. |
| `initialBehaviorMode` | `"FULL"` | How the bar first appears. `"FULL"` — input and starters visible. `"COMPACT"` — icon only (plus optional internal label if configured elsewhere). |
| `openEmbeddedCallback` | none | Callback invoked to reveal your embedded agent container when the user submits from the bar or opens the agent from the bar menu. **Required in `EMBEDDED` mode** — without it the Bottom Bar will not render. The prompt is delivered to the agent separately; this callback only makes the container visible. |

:::note[Embedded mode]
`openEmbeddedCallback` is required in `EMBEDDED` mode. See [Embedded mode](/guides/embedded-agent/).
:::

## Examples

### At init

```javascript
foldspace('when', 'ready', () => {
  const agent = foldspace.agent({
    apiName: 'YOUR-AGENT-KEY',
    mode: 'OVERLAY',
    configuration: {
      bottomBarSettings: {
        // Master gate — must be literal `true` to render
        enabled: true,
        maxVisibleStarters: 5, // mobile render cap: 3 (not configurable)
        reopenFrequency: 'EVERY_LOAD', // 'EVERY_LOAD' | 'NEVER' | 'AFTER_DAYS'
        reopenFrequencyDays: 30,       // min 1; only used when reopenFrequency is 'AFTER_DAYS'
        starterClickBehavior: 'OPEN_AGENT', // 'OPEN_AGENT' | 'FILL_INPUT'
        idleTimeoutMs: 5000, // auto-compact in FULL; 0 disables
        initialBehaviorMode: 'FULL', // 'FULL' | 'COMPACT'
      },
    },
  });
});
```

### At runtime

```javascript
const agent = foldspace.agent('YOUR-AGENT-KEY');

agent.setConfiguration({
  bottomBarSettings: {
    enabled: true,
    maxVisibleStarters: 5,
    reopenFrequency: 'EVERY_LOAD',
    reopenFrequencyDays: 30,
    starterClickBehavior: 'OPEN_AGENT',
    idleTimeoutMs: 5000,
    initialBehaviorMode: 'FULL',
    // Required in EMBEDDED mode; no default
    openEmbeddedCallback: () => { /* reveal embedded container */ },
  },
});
```

## openBottomBar

Open or expand the Bottom Bar programmatically. No-op when `enabled` is not `true`.

```javascript
agent.openBottomBar(); // defaults to FULL

agent.openBottomBar({
  mode: 'FULL', // 'FULL' | 'COMPACT'
  idleTimeoutMs: 8000, // override idleTimeoutMs for this open only (FULL mode)
});
```

### Route changes with page-specific starters

When navigation brings the user to a page with its own starters, update the starters and surface the bar:

```javascript
function onRouteChange(route) {
  agent.setConversationStarters(route.starters, route.defaultStarterType);
  agent.openBottomBar({ mode: 'FULL' });
}
```

Typical trigger points: SPA route-change handlers, framework router `afterNavigate` hooks, or post–`setConfiguration` when page-level config is applied.