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

# Customise the Flutter chat

> Placement, colours, header, cards and text of the Flutter chat widgets

The Flutter SDK has two widgets. Both take the same options.

| Widget | What it is | Use it when |
| - | - | - |
| `OsviChatLauncher` | A floating button with an unread badge. Tapping it opens the chat full screen | You want chat available from a screen without changing its layout. Start here |
| `OsviChatView` | The chat panel itself: header, transcript, cards and composer | The chat belongs inside a screen, a tab or a bottom sheet |

`OsviChatLauncher.open(context, client: …)` opens the full-screen chat from any button of your own, and completes when the visitor closes it.

## What the dashboard controls

These settings in **Channels → Web widget** apply in the app automatically, with no release: the brand colour, light or dark mode, the title, the welcome message, the pre-chat form and the WhatsApp hand-off. Anything you set in the app wins over the dashboard.

## Options

```dart theme={null}
OsviChatView(
  client: chat,
  title: 'Help',
  subtitle: 'We reply in minutes',
  avatarUrl: 'https://example.com/avatar.png',
  theme: const OsviChatTheme(
    colors: OsviChatColorOverrides(primary: Color(0xFF0B6A87)),
    mode: OsviThemeMode.auto,
    radius: 16,
    buttons: OsviButtonsVariant.list,
    carousel: OsviCarouselVariant.slider,
  ),
  strings: const OsviChatStrings(placeholder: 'Ask us anything…'),
  newChatKeepsHistory: true,
  onPrechat: (visitor) => debugPrint('Pre-chat saved: ${visitor.toJson()}'),
  onClose: () => Navigator.of(context).pop(),
);
```

| Option | Default | What it does |
| - | - | - |
| `client` | Required | The `OsviChatClient` to show. Several widgets can share one client |
| `title` | Dashboard title, then the agent's name, then "Chat" | Header title |
| `subtitle` | None | A line under the title |
| `avatarUrl` | The title's first letter | An `https` image for the header |
| `theme` | Light theme | Colours, shape, mode and card layout. See below |
| `strings` | English | Every visible text. See [Text and language](#text-and-language) |
| `showNewChat` | `true` | Shows the **New chat** button in the header |
| `newChatKeepsHistory` | `false` | Keeps the old conversation above a "Conversation ended" divider when the visitor starts a new chat. Otherwise the transcript is cleared |
| `showPoweredBy` | `true` | Shows the "Powered by Osvi AI" footer |
| `onPrechat` | None | Called once the visitor submits the pre-chat form |
| `onClose` | None | `OsviChatView` only. Shows a close button in the header that calls it. The launcher sets it for you |

## Colours and shape

`OsviChatTheme` takes:

| Field | Default | Notes |
| - | - | - |
| `colors` | Built-in light or dark palette | `OsviChatColorOverrides` with any of `primary`, `background`, `surface`, `text`, `userBubble` and `assistantBubble`. Unset colours keep the defaults. The visitor's bubble follows `primary` unless you set `userBubble` |
| `mode` | The dashboard setting, then light | `OsviThemeMode.light`, `.dark` or `.auto`, which follows the device |
| `radius` | `10` | Corner radius of bubbles, cards and buttons, in logical pixels |
| `cardMaxWidth` | `340` | Maximum width of buttons, carousels and date pickers |
| `buttons` | `OsviButtonsVariant.chips` | How button choices look: `chips` or a full-width `list` |
| `carousel` | `OsviCarouselVariant.slider` | How carousels look: a swipeable `slider` or a vertical `list` |
| `fontFamily` | Your app's font | A font family registered in your app |

The SDK does not read your app's `ThemeData`. Pass your brand colour in `colors.primary`, or set it in the dashboard.

## Interactive tools

The agent's [interactive UI elements](https://docs.osvi.ai/platform/chat-agents.md#interactive-ui-elements) appear as cards:

* **Buttons:** chips or a list. If the agent allows a free-text answer, the visitor can type one in the composer instead.
* **Carousel:** a slider or a list of cards with images, a title, a description and a select button. Images load through Osvi AI's image proxy; a card whose image cannot load shows "Image unavailable".
* **Date picker:** a single date or a range, within the dates the agent allows.

While a team member is connected, card answers are paused, as on the website.

## Text and language

Every visible string can be replaced. Pass only the ones you change:

```dart theme={null}
const OsviChatStrings(
  placeholder: 'Écrivez votre message…',
  send: 'Envoyer',
  newChat: 'Nouvelle discussion',
  defaultTitle: 'Discussion',
);
```

The keys match the website widget's text keys, plus a few for text the website panel does not let you change, such as `team`, `select`, `confirmDate`, `openChat` and `unread`. Strings with placeholders keep them: `rateLimitedRetry` uses `{time}`, `unread` uses `{count}`, `cardPosition` uses `{index}` and `{count}`.

## Accessibility

Status changes and new replies are announced to screen readers, focus moves to a new card, buttons have labels, and the typing animation stops when the device asks for reduced motion.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.