> For the complete documentation index, see [llms.txt](https://docs.ibexa.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ibexa.ai/developers/assistant/options.md).

# Options

The Assistant component accepts a variety of props that allow you to customize its behavior and appearance. Below is a list of the available options and their descriptions.

## Adapter

The `adapter` property is required to connect the Assistant to a data source. It should be an instance of a class that implements the Adapter interface. The adapter is responsible for handling the communication between the Assistant and the backend, including sending user messages and receiving responses.

```jsx
import { Assistant, EchoAdapter } from '@ibexa/ai-assistant-ui';

function App() {
    const adapter = new EchoAdapter();

    return (
        <Assistant
            adapter={adapter}
            // other props...
        />
    );
}
```

## Allow Conversation Management

The `allowConversationManagement` property allows you to enable the conversation management features in the Assistant. If set to `true`, users will be able to view the list of conversations, switch between conversations, create and delete conversations. If set to `false`, the conversation management features will be hidden, and users will not be able to manage their conversations.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    return (
        <Assistant
            allowConversationManagement={true}
            // other props...
        />
    );
}
```

## Allow Fullscreen

The `allowFullscreen` property allows you to enable the option to switch to full-screen mode from other layouts (e.g. floating or sidebar). If set to `true`, a full-screen button will be displayed in the Assistant header, allowing users to switch to full-screen mode. If set to `false`, the full-screen button will be hidden, and users will not be able to switch to full-screen mode.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    return (
        <Assistant
            allowFullscreen={true}
            // other props...
        />
    );
}
```

## Avatar

The `avatar` property allows you to set an avatar for the Assistant. This can help personalize the Assistant and make it more visually appealing to users. The `avatar` property should be an object with the following properties:

* `imageUrl`: A URL to the avatar image.
* `name`: A name for the avatar e.g. "Assistant", "Support Bot", etc.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    return (
        <Assistant
            avatar={{ imageUrl: 'https://example.com/avatar.png', name: 'Assistant' }}
            // other props...
        />
    );
}
```

## Backdrop

The `backdrop` property allows you to display a dimmed overlay behind the Assistant window. When set to `true`, a backdrop is rendered behind the Assistant, helping it stand out from the rest of the page. Clicking the backdrop closes the Assistant (unless the `closeable` property is set to `false`), which in turn triggers the `onOpenChange` callback. The backdrop has no effect when using the `embedded` layout. Defaults to `false`.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    return (
        <Assistant
            backdrop={true}
            // other props...
        />
    );
}
```

## Closable

The `closable` property allows you to specify whether the Assistant can be closed by the user. If set to `true`, the Assistant will have a close button in the header, allowing users to close the Assistant window. If set to `false`, the close button will be hidden, and users will not be able to close the Assistant.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    return (
        <Assistant
            closeable={false}
            // other props...
        />
    );
}
```

## Confirmation Handler

The `onConfirmation` prop allows you to provide a custom confirmation handling function that will be called whenever the Assistant needs to confirm an action with the user. This can be useful to perform specific logic based on user confirmations, such as deleting a conversation, sending a message, or any other action that requires user confirmation. The value should be a function that takes the confirmation message and a callback to execute when the user confirms the action.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    const handleConfirmation = (message, onConfirm) => {
        console.log('User confirmed an action:', message);
        onConfirm();
    };

    return (
        <Assistant
            onConfirmation={handleConfirmation}
            // other props...
        />
    );
}
```

## Current User

The `currentUser` property allows you to specify the current user of the Assistant. This can be useful for personalizing the experience and providing user-specific functionality. The `currentUser` property should be an object with the following properties:

* `id`: A unique identifier for the user.
* `name`: The name of the user.
* `imageUrl`: A URL to the user's avatar image.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    return (
        <Assistant
            currentUser={{ id: 'user123', name: 'John Doe', imageUrl: 'https://example.com/user-avatar.png' }}
            // other props...
        />
    );
}
```

## Error Handler

The `onError` property allows you to provide a custom error handling function that will be called whenever an error occurs within the Assistant. This can be useful to log errors, display custom error messages to users, or perform any other error handling logic specific to your application. The value should be a function that takes an error object as its argument.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    const handleError = (error) => {
        console.error('An error occurred in the Assistant:', error);
        // You can also display a custom error message to users here
    };

    return (
        <Assistant
            onError={handleError}
            // other props...
        />
    );
}
```

## Height

The `height` property allows you to set a custom height for the Assistant when using the `floating` or `sidebar` layout. The value should be a string representing the height in CSS units (e.g., `400px`, `50vh`, etc.). This can be useful to ensure that the Assistant fits well within your application's layout and provides an optimal user experience.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    return (
        <Assistant
            layout="floating"
            height="400px"
            // other props...
        />
    );
}
```

## Hotkeys

The `hotkeys` property allows you to define custom keyboard shortcuts for various actions within the Assistant. This can enhance the user experience by providing quick access to common functions without needing to navigate through the interface. The value should be an object where each key is a string representing the action (e.g., 'activate', 'newConversation', etc.) and the value is a string representing the keyboard shortcut (e.g., 'ctrl+k', 'cmd+n', etc.).

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    const hotkeys = {
        activate: 'ctrl+k',
        newConversation: 'ctrl+n',
        deactivate: 'ctrl+w',
    };

    return (
        <Assistant
            hotkeys={hotkeys}
            // other props...
        />
    );
}
```

Available actions for hotkeys are:

* `activate`: Activate or open the Assistant.
* `deactivate`: Deactivate or close the Assistant.
* `sendMessage`: Send the current message in the input field.
* `newConversation`: Start a new conversation.
* `attachFile`: Open the file attachment dialog.
* `toggleMicrophone`: Toggle the microphone for voice input.
* `toggleFullscreen`: Toggle between fullscreen and the previous layout.
* `toggleSidebar`: Toggle the visibility of the sidebar (if the layout supports it).

For a syntax reference, see: [react-hotkeys-hook](https://react-hotkeys-hook.vercel.app/docs/documentation/useHotkeys/basic-usage).

## Initial Conversation ID

The `initialConversationId` property allows you to specify the ID of the last conversation that should be loaded when the Assistant is initialized. This can be useful if you want to restore a previous conversation or load a specific conversation from the backend.

```jsx
import { Assistant, EchoAdapter } from '@ibexa/ai-assistant-ui';

function App() {
    return (
        <Assistant
            initialConversationId="12345"
            // other props...
        />
    );
}
```

## Input Config

The `inputConfig` property allows you to customize the behavior and appearance of the input field in the Assistant. It should be an object that can contain the following properties:

### Mode

The `inputConfig.mode` property allows you to specify the allowed input modes for the Assistant. The available modes are:

* `text`: Allows users to input text messages.
* `file`: Allows users to attach files.
* `voice`: Allows users to input messages using voice.

You can choose to enable or disable specific input modes based on your application's requirements. For example, if you want to allow only text and file inputs while disabling voice input, you can set the `modes` property as follows:

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    return (
        <Assistant
            inputConfig={{
                modes: ['text', 'file'], // Only allow text and file inputs, disable voice input
            }}
            // other props...
        />
    );
}
```

### Text Max Length

The `inputConfig.text.maxLength` property allows you to set a maximum length for the text input field in the Assistant. This can be useful to limit the length of user messages and ensure that they are concise. The value should be a positive integer representing the maximum number of characters allowed in the input field.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    return (
        <Assistant
            inputConfig={{
                text: {
                    maxLength: 300, // Set maximum length for text input to 300 characters
                },
            }}
            // other props...
        />
    );
}
```

### Text Growth Behaviour

The `inputConfig.text.growth` property controls how the input textarea sizes itself. Accepted values are `'growth'` (default) and `'fixed'`. With `'growth'`, the textarea expands with the content up to a maximum height; with `'fixed'`, it stays at a constant height and scrolls internally.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    return (
        <Assistant
            inputConfig={{
                text: {
                    growth: 'fixed', // Keep the input textarea at a fixed height
                },
            }}
            // other props...
        />
    );
}
```

### File Max Size

The `inputConfig.file.maxSize` property allows you to set a maximum file size for attachments in the Assistant. This can be useful to prevent users from uploading excessively large files that may cause performance issues or exceed backend limitations. The value should be a positive integer representing the maximum file size in bytes.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    return (
        <Assistant
            inputConfig={{
                file: {
                    maxSize: 5 * 1024 * 1024, // Set maximum file size to 5 MB
                },
            }}
            // other props...
        />
    );
}
```

### Allowed File Types

The `inputConfig.file.allowedTypes` property allows you to specify a list of allowed file types for attachments in the Assistant. This can be useful to restrict the types of files that users can upload and ensure that they are compatible with your application's requirements. The value should be an array of strings representing the allowed MIME types (e.g., `['image/jpeg', 'application/pdf']`).

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    return (
        <Assistant
            inputConfig={{
                file: {
                    allowedTypes: ['image/*', 'application/pdf'], // Only allow images and PDF files
                },
            }}
            // other props...
        />
    );
}
```

### `inputConfig.linkProtocols`

The `inputConfig.linkProtocols` property lets you allow additional URL schemes (beyond the built-in `http`, `https`, `mailto`, `tel`, etc.) to be treated as links. This applies both to links typed or pasted into the input (e.g. `[Open](cms://location/2)`) and to links rendered in the message history — a link with a scheme that is not listed has its `href` stripped during sanitization. The value should be an array of scheme names (without `://`). It defaults to an empty array, so custom schemes are opt-in.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    return (
        <Assistant
            inputConfig={{
                linkProtocols: ['cms'], // Treat cms://... as valid links, e.g. cms://location/2
            }}
            // other props...
        />
    );
}
```

## Input Actions

The `inputActions` property allows you to add custom action buttons to the chat input area. The actions are collected in a dropdown menu opened from the `+` button next to the chat input (alongside the built-in file attachment action) and can be used to trigger application-specific actions such as opening a content picker, selecting a product, or any other custom behavior. The value should be an array of objects with the following properties:

| Property   | Type         | Required | Description                                                                                                                                   |
| ---------- | ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `label`    | `string`     | Yes      | Button label text.                                                                                                                            |
| `onClick`  | `() => void` | Yes      | Callback invoked when the button is clicked.                                                                                                  |
| `icon`     | `ReactNode`  | No       | Icon rendered inside the button, before the label.                                                                                            |
| `shortcut` | `string`     | No       | Keyboard shortcut that triggers the action (e.g. `'ctrl+shift+c'`). Uses [react-hotkeys-hook](https://react-hotkeys-hook.vercel.app/) syntax. |
| `priority` | `number`     | No       | Rendering order within the menu. Lower values appear first. Actions without a priority appear last.                                           |

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    const inputActions = [
        {
            label: 'Select content',
            onClick: () => openContentPicker(),
            icon: <ContentIcon />,
            shortcut: 'ctrl+shift+c',
            priority: 1,
        },
        {
            label: 'Select product',
            onClick: () => openProductPicker(),
            icon: <ProductIcon />,
            shortcut: 'ctrl+shift+p',
            priority: 2,
        },
        {
            label: 'Settings',
            onClick: () => openSettings(),
        },
    ];

    return (
        <Assistant
            inputActions={inputActions}
            // other props...
        />
    );
}
```

## Fetch Mentions

The `fetchMentions` prop enables `@mention` support in the chat input. When provided, typing `@` opens a suggestion popup that filters results in real time as the user continues typing. Selecting an item inserts a styled chip into the message; clicking the chip opens the associated link in a new tab.

The prop accepts a function that receives the current query string and returns either an array or a Promise resolving to an array of `MentionItem` objects:

```typescript
interface MentionItem {
    id: string;
    label: string;
    link: string;
}
```

A loading spinner is shown while the Promise is pending.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    const fetchMentions = async (query) => {
        const users = await searchUsers(query);
        return users.map((u) => ({ id: u.id, label: u.name, link: u.profileUrl }));
    };

    return (
        <Assistant
            fetchMentions={fetchMentions}
            // other props...
        />
    );
}
```

### Markdown Input Rules

The chat input supports Markdown shortcuts typed inline — the editor converts them to formatted content as you type.

| Syntax                   | Result            |
| ------------------------ | ----------------- |
| `**text**` or `__text__` | Bold              |
| `*text*` or `_text_`     | Italic            |
| `~~text~~`               | Strikethrough     |
| `` `code` ``             | Inline code       |
| ` ``` ` + Enter          | Code block        |
| `>` + Space              | Blockquote        |
| `-` or `*` + Space       | Bullet list item  |
| `1.` + Space             | Ordered list item |

Standard formatting keyboard shortcuts are also available: `Ctrl`/`Cmd` + `B` (bold), `Ctrl`/`Cmd` + `I` (italic), `Ctrl`/`Cmd` + `Z` / `Shift`+`Z` (undo/redo).

## Message Actions

The `messageActions` property allows you to add custom action buttons to each message in the conversation. These buttons are rendered below the message content and can be used to trigger application-specific actions such as copying a response, forking a conversation, or submitting feedback. The value should be an array of objects with the following properties:

| Property  | Type                                  | Required | Description                                                                                           |
| --------- | ------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `label`   | `string`                              | Yes      | Button label text. Displayed when no icon is provided; used as the accessible label otherwise.        |
| `onClick` | `(message: MessageInterface) => void` | Yes      | Callback invoked when the button is clicked. Receives the message object the action was triggered on. |
| `icon`    | `ReactNode`                           | No       | Icon rendered inside the button. When provided, the icon is shown instead of the label text.          |

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    const messageActions = [
        {
            label: 'Copy',
            icon: <CopyIcon />,
            onClick: (message) => navigator.clipboard.writeText(message.content),
        },
        {
            label: 'Good response',
            icon: <ThumbUpIcon />,
            onClick: (message) => submitFeedback(message, 'positive'),
        },
        {
            label: 'Bad response',
            icon: <ThumbDownIcon />,
            onClick: (message) => submitFeedback(message, 'negative'),
        },
    ];

    return (
        <Assistant
            messageActions={messageActions}
            // other props...
        />
    );
}
```

## Input Preview Components

The `inputPreviewComponents` property allows you to provide custom React components for rendering attachment previews in the Assistant. This can be useful to create a more personalized and engaging user experience by customizing the appearance of input previews based on their type, content, or any other criteria. The value should be an object where each key is a string representing the input type (e.g., 'file', 'image', etc.) and the value is a React component that will be used to render input previews of that type.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    const inputPreviewComponents = {
        file: ({ file }) => <div style={{ padding: '10px', border: '1px solid #ccc' }}>{file.name}</div>,
    };

    return (
        <Assistant
            inputPreviewComponents={inputPreviewComponents}
            // other props...
        />
    );
}
```

## Is Open

The `isOpen` property allows you to control the visibility of the Assistant. If set to `true`, the Assistant will be visible and open when the component is rendered. If set to `false`, the Assistant will be hidden and closed when the component is rendered. This can be useful for controlling when the Assistant is displayed based on user interactions or application state.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    return (
        <Assistant
            isOpen={true}
            // other props...
        />
    );
}
```

## On Conversation Change

The `onConversationChange` callback is called whenever the active conversation changes. Use this to persist the current conversation ID in the host application (e.g. user settings) so the same conversation can be restored on the next page load via `initialConversationId`. The callback receives the server-side ID of the newly active conversation as a string, or `null` when a new draft conversation is started that has not yet been persisted.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    const handleConversationChange = (conversationId) => {
        if (conversationId) {
            saveToUserSettings('conversationId', conversationId);
        }
    };

    return (
        <Assistant
            onConversationChange={handleConversationChange}
            // other props...
        />
    );
}
```

## On Open Change

The `onOpenChange` callback is called whenever the Assistant open/closed state changes. Use this to persist the open state in the host application (e.g. user settings) or to keep external UI in sync with the Assistant visibility. The callback receives a boolean argument that is `true` when the Assistant window opens and `false` when it closes.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    const handleOpenChange = (isOpen) => {
        console.log('Assistant is now', isOpen ? 'open' : 'closed');
        // e.g. persist state: saveToUserSettings('chatbotOpen', isOpen);
    };

    return (
        <Assistant
            onOpenChange={handleOpenChange}
            // other props...
        />
    );
}
```

## On Close

The `onClose` callback is called when the Assistant window transitions from open to closed. Note that close interactions are disabled when `closeable={false}`, and always-open layouts (e.g. `embedded`, `fullscreen`) never close, so `onClose` will not fire in those cases. If you need to track both open and close transitions, use `onOpenChange` instead.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    const handleClose = () => {
        console.log('Assistant closed');
        // e.g. trackEvent('assistant_closed');
    };

    return (
        <Assistant
            onClose={handleClose}
            // other props...
        />
    );
}
```

## On Network Status Change

The `onNetworkStatusChange` callback is called whenever the Assistant's network connectivity status changes, while the Assistant window is open. The Assistant already shows its own offline indicator and disables its input automatically — use this callback only if the host application needs to react as well, e.g. to show a global banner or disable unrelated features that also require network access. The callback receives a boolean argument that is `true` when the Assistant regains connectivity and `false` when it goes offline.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    const handleNetworkStatusChange = (isOnline) => {
        console.log(isOnline ? 'Back online' : 'Gone offline');
    };

    return (
        <Assistant
            onNetworkStatusChange={handleNetworkStatusChange}
            // other props...
        />
    );
}
```

## Layout

The `layout` property allows you to choose the layout of the Assistant. The available layout options are:

* `floating`: Renders the Assistant as a small floating window.
* `sidebar`: Renders the Assistant as a sliding panel.
* `fullscreen`: Renders the Assistant to cover the entire screen.
* `embedded`: Renders the Assistant within a specified container in the existing user interface.

To see more details about each layout and how to choose the right one for your use case, check the [Layouts](/developers/assistant/layouts.md) page.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    return (
        <Assistant
            layout="sidebar"
            // other props...
        />
    );
}
```

## Locale

The `locale` property allows you to set the locale for the Assistant. Allowed values are `en`, `fr`, `de`, `es`.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    return (
        <Assistant
            locale="fr"
            // other props...
        />
    );
}
```

## Message Components

The `messageComponents` property allows you to provide custom React components for rendering messages in the Assistant. This can be useful to create a more personalized and engaging user experience by customizing the appearance of messages based on their type, content, or any other criteria. The value should be an object where each key is a string representing the message type (e.g., 'text', 'image', 'file', etc.) and the value is a React component that will be used to render messages of that type.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    const messageComponents = {
        custom: ({ message }) => <img src={message.content} alt="Custom" style={{ maxWidth: '100%' }} />,
    };

    return (
        <Assistant
            messageComponents={messageComponents}
            // other props...
        />
    );
}
```

## Translations

The `translations` property allows you to provide custom translations for various messages and labels used in the Assistant. This can be useful to customize the language and tone of the Assistant to better fit your application's context and user base. The value should be an object where each key is a string representing the `react-intl` message identifier (e.g., 'ibexa.ai\_assistant.send\_button.title', 'ibexa.ai\_assistant.chat\_input.placeholder', etc., as defined in the translations) and the value is a string representing the custom message or label.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    const translations = {
        'ibexa.ai_assistant.send_button.title': 'Send Message',
        'ibexa.ai_assistant.chat_input.placeholder': 'Type your message here...',
    };

    return (
        <Assistant
            translations={translations}
            // other props...
        />
    );
}
```

## Position

The `position` property allows you to set the position of the Assistant when using the `floating` layout. The value should be an object with the following properties:

* `x`: A string representing the distance from the left side of the screen (e.g., `20px`, `5vw`, etc.).
* `y`: A string representing the distance from the top of the screen (e.g., `20px`, `5vh`, etc.).

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    return (
        <Assistant
            layout="floating"
            position={{ x: '20px', y: '20px' }}
            // other props...
        />
    );
}
```

## Title

You can pass the `title` property to the Assistant component to set a default title for the Assistant window. It is displayed in the header of the Assistant in case no subtitle is provided by the adapter. It can be used to provide a more descriptive name for the Assistant, e.g. "Support Assistant", "Content Creation Assistant", etc.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    return (
        <Assistant
            title="My Custom Assistant"
            // other props...
        />
    );
}
```

## Welcome Message

The `welcomeMessage` property allows you to set a custom welcome message that will be displayed to users when they open the Assistant for the first time. This can be useful to provide a friendly greeting, instructions, or any important information you want users to see before they start interacting with the Assistant.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    return (
        <Assistant
            welcomeMessage="Hello! I'm here to assist you. How can I help you today?"
            // other props...
        />
    );
}
```

## Welcome Message Suggestions

The `welcomeMessageSuggestions` property allows you to provide a list of suggested messages that users can click on to quickly start a conversation with the Assistant. This can be useful to guide users towards common questions or actions and improve their experience with the Assistant. The value should be an array of suggestion objects, where each object has an `id`, a `title`, and a `prompt` field describing the suggested message.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    const suggestions = [
        {
            id: 'hello',
            title: 'Say Hello',
            prompt: 'Hello!',
        },
        {
            id: 'capabilities',
            title: 'Capabilities',
            prompt: 'What are your capabilities?',
        },
    ];

    return (
        <Assistant
            welcomeMessage="Hello! I'm here to assist you. How can I help you today?"
            welcomeMessageSuggestions={suggestions}
            // other props...
        />
    );
}
```

## Welcome Screen

The `welcomeScreen` property allows you to provide a fully custom React component to be displayed instead of the built-in welcome message when a user opens a new conversation. This can be useful when you need complete control over the initial screen shown to users, e.g. custom branding, quick-start actions, or a layout that goes beyond a simple message and suggestion list. If not provided, the Assistant falls back to the built-in welcome message composed from the `welcomeMessage` and `welcomeMessageSuggestions` properties.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function CustomWelcomeScreen() {
    return (
        <div>
            <h2>Welcome!</h2>
            <p>Ask me anything about your project.</p>
        </div>
    );
}

function App() {
    return (
        <Assistant
            welcomeScreen={<CustomWelcomeScreen />}
            // other props...
        />
    );
}
```

### Login Screen

The library ships a ready-made `LoginScreen` component you can pass to `welcomeScreen` to require authentication before a conversation starts. It renders a username/password form and, when an `onSSO` callback is provided, a "Sign in with SSO" button.

`LoginScreen` is presentational: it manages its own field, loading, and error UI, but delegates the actual authentication to your callbacks. Return a promise from `onSubmit` to keep the form in its loading state until authentication resolves; throw (or reject) to display the error inline. You decide when to leave the login view — typically by swapping the `welcomeScreen` prop once authenticated. For SSO, `onSSO` is invoked when the button is clicked and your app is responsible for opening the SSO window (in a separate window/popup) and handling its completion.

To actually prevent the user from starting a conversation before authenticating, pass the Assistant's `hideInputOnWelcomeScreen` prop — while the `welcomeScreen` is shown, the chat input is hidden, and it returns automatically once you remove the `welcomeScreen` after login.

| Prop          | Type                                                                             | Required | Description                                                                           |
| ------------- | -------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------- |
| `onSubmit`    | `(credentials: { username: string; password: string }) => void \| Promise<void>` | Yes      | Called when the form is submitted.                                                    |
| `onSSO`       | `() => void`                                                                     | No       | Called when the SSO button is clicked. The button is only rendered when provided.     |
| `title`       | `ReactNode`                                                                      | No       | Overrides the default heading.                                                        |
| `description` | `ReactNode`                                                                      | No       | Overrides the default sub-heading.                                                    |
| `error`       | `string`                                                                         | No       | Host-controlled error message; takes precedence over an error thrown from `onSubmit`. |

```jsx
import { useState } from 'react';
import { Assistant, LoginScreen } from '@ibexa/ai-assistant-ui';

function App() {
    const [authenticated, setAuthenticated] = useState(false);

    return (
        <Assistant
            hideInputOnWelcomeScreen
            welcomeScreen={
                authenticated ? undefined : (
                    <LoginScreen
                        onSubmit={async ({ username, password }) => {
                            await myApi.login(username, password); // throw to show an inline error
                            setAuthenticated(true);
                        }}
                        onSSO={() => {
                            // Start the SSO flow in a separate window and mark the user
                            // authenticated once it completes (e.g. via a postMessage handler).
                            window.open('https://id.example.com/sso', 'sso', 'width=480,height=640');
                        }}
                    />
                )
            }
            // other props...
        />
    );
}
```

#### SSO in a Separate Window

`onSSO` is called when the user clicks the SSO button; opening the window and handling completion is up to the host. The recommended pattern is to open a popup and wait for it to post the result back with `window.postMessage`, verifying the message's origin:

```javascript
const SSO_URL = 'https://id.example.com/sso/authorize';
const SSO_ORIGIN = 'https://id.example.com'; // exact origin of the callback page — never '*'

function startSSOLogin(onAuthenticated) {
    const state = crypto.randomUUID(); // round-tripped to tie the response to this request (CSRF defense)
    const popup = window.open(`${SSO_URL}?state=${state}`, 'ai-assistant-sso', 'width=480,height=640');

    if (!popup) {
        // Popup blocked — surface this to the user.
        return;
    }

    const onMessage = (event) => {
        // Only trust messages from the SSO origin, from the popup we opened, matching our state.
        if (event.origin !== SSO_ORIGIN || event.source !== popup) return;
        if (event.data?.type !== 'sso-auth' || event.data.state !== state) return;

        window.removeEventListener('message', onMessage);
        popup.close();
        onAuthenticated(event.data.token);
    };

    window.addEventListener('message', onMessage);
}
```

The SSO callback page (served on `SSO_ORIGIN`) hands the result back and closes itself. Prefer the OAuth `code` flow so a real token never travels through `postMessage`/the URL:

```html
<script>
    const params = new URLSearchParams(window.location.search);
    window.opener?.postMessage(
        { type: 'sso-auth', state: params.get('state'), token: params.get('token') },
        'https://your-app.example.com', // your app's exact origin — never '*'
    );
    window.close();
</script>
```

## Width

The `width` property allows you to set a custom width for the Assistant when using the `floating` layout. The value should be a string representing the width in CSS units (e.g., `300px`, `30vw`, etc.). This can be useful to ensure that the Assistant fits well within your application's layout and provides an optimal user experience.

```jsx
import { Assistant } from '@ibexa/ai-assistant-ui';

function App() {
    return (
        <Assistant
            layout="floating"
            width="300px"
            // other props...
        />
    );
}
```