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

# updateCustomHeaderItems()

Updates the display of custom items that appear in the chat header. It provides a container for custom items which can be either menu items or dropdown menus. Each item is configurable with a custom callback function that is called when a user selects an item.

The method accepts an array of objects that define the properties of each custom header item. You can call this method anytime to change the current set of options.

## Syntax

```javascript theme={null}
instance.updateCustomHeaderItems(items);
```

## Parameters

<ParamField path="items" type="array" required>
  An array of custom header items to display. Each item is an object that defines the properties of the header element.
</ParamField>

### `items` properties

<ParamField path="id" type="string" required>
  A unique identifier for the header item.
</ParamField>

<ParamField path="text" type="array" required>
  The text to display for the header item.
</ParamField>

<ParamField path="align" type="string">
  The alignment of the header item. Possible values: `left` (default) or `right`.
</ParamField>

<ParamField path="icon" type="string">
  A URL or data URI to an icon image to display alongside the text.
</ParamField>

<ParamField path="type" type="string" required>
  The type of header item. Possible values: `menu-item` or `dropdown`. Default: `menu-item`.
</ParamField>

<ParamField path="onClick" type="function">
  A callback function called when the button is clicked. <Badge color="red">Required</Badge> for `menu-item` type.
</ParamField>

<ParamField path="items" type="array">
  An array of submenu items for the dropdown. <Badge color="red">Required</Badge> for `dropdown` type. |
</ParamField>

### `dropdown` specific properties

<ParamField path="showSelectedAsTitle" type="boolean">
  When set to `true`, the detail view title automatically updates to show the text of the currently selected dropdown item. When set to `false` (default), the detail view title displays the dropdown's main label.
</ParamField>

### Layout compatibility

|                       | `fullscreen-overlay` | `float`               | `custom`              |
| --------------------- | -------------------- | --------------------- | --------------------- |
| `showSelectedAsTitle` | <Icon icon="x" />    | <Icon icon="check" /> | <Icon icon="check" /> |

### `dropdown` submenu item properties

<ParamField path="id" type="string" required>
  A unique identifier for the submenu item.
</ParamField>

<ParamField path="text" type="string" required>
  The text to display for the submenu item.
</ParamField>

<ParamField path="align" type="string">
  The alignment of the submenu item. Possible values: `left` (default) or `right`.
</ParamField>

<ParamField path="icon" type="string">
  A URL or data URI to an icon image to display alongside the submenu item text.
</ParamField>

<ParamField path="onClick" type="function" required>
  A callback function called when the submenu item is clicked.
</ParamField>

## Returns

<ResponseField name="void">
  Returns a `void` operator.
</ResponseField>

## Examples

The following example creates a help button as menu item:

```javascript theme={null}
instance.updateCustomHeaderItems([
    {
        id: 'help-button',
        text: 'Help',
        align: 'right',
        icon: 'https://example.com/help-icon.svg',
        type: 'menu-item',
        onClick: () => {
            window.open('https://example.com/help', '_blank');
        }
    }
]);
```

The following example creates a settings dropdown:

```javascript theme={null}
instance.updateCustomHeaderItems([
    {
        id: 'settings-menu',
        text: 'Settings',
        align: 'right',
        icon: 'https://example.com/settings-icon.svg',
        type: 'dropdown',
        items: [
            {
                id: 'profile',
                text: 'Profile',
                align: 'left',
                icon: 'https://example.com/profile-icon.svg',
                onClick: () => console.log('Profile clicked')
            },
            {
                id: 'preferences',
                text: 'Preferences',
                align: 'left',
                icon: 'https://example.com/preferences-icon.svg',
                onClick: () => console.log('Preferences clicked')
            }
        ]
    }
]);
```

The following example demonstrates the `showSelectedAsTitle` property, which updates dynamically the detail view title to display the selected item's text. In the example, when a user selects "Spanish", the detail view title automatically updates from "Language" to "Spanish":

```javascript theme={null}
instance.updateCustomHeaderItems([
    {
        id: 'language',
        type: 'dropdown',
        text: 'Language',
        showSelectedAsTitle: true,  // Title updates to show selected language
        items: [
            {
                id: 'en',
                text: 'English',
                onClick: () => {
                    console.log('English selected');
                }
            },
            {
                id: 'es',
                text: 'Spanish',
                onClick: () => {
                    console.log('Spanish selected');
                }
            },
            {
                id: 'fr',
                text: 'French',
                onClick: () => {
                    console.log('French selected');
                }
            }
        ]
    }
]);
```

The following example demonstrates a dynamic language selector that updates both the chat locale and the dropdown display text when a language is selected. The selector uses a globe icon and displays the current language name, with options for English, Spanish, and French.

```javascript theme={null}
const ICONS = {
    globe: 'data:image/svg+xml;base64,' + btoa('<svg>...</svg>')
};

const updateMenuItems = (locale) => {
    const languageNames = {
        en: 'English',
        es: 'Español',
        fr: 'Français'
    };
    
    instance.updateCustomHeaderItems([
        {
            id: 'language-selector',
            text: languageNames[locale],
            type: 'dropdown',
            icon: ICONS.globe,
            items: [
                {
                    id: 'lang-en',
                    text: 'English',
                    onClick: () => {
                        instance.updateLocale('en');
                        updateMenuItems('en');
                    }
                },
                {
                    id: 'lang-es',
                    text: 'Español',
                    onClick: () => {
                        instance.updateLocale('es');
                        updateMenuItems('es');
                    }
                },
                {
                    id: 'lang-fr',
                    text: 'Français',
                    onClick: () => {
                        instance.updateLocale('fr');
                        updateMenuItems('fr');
                    }
                }
            ]
        }
    ]);
};

// Initialize with English
updateMenuItems('en');
```

## Considerations

### Layout support

Chat header customization is available for all form layouts: `fullscreen-overlay`, `float`, and `custom`.

#### Float layout

All custom items always appear in the side panel because Float has a fixed width of 380px.

#### Dropdown behavior by layout

Dropdown items behave differently based on form layout:

| Form layout | Dropdown behavior      | Navigation pattern           |
| ----------- | ---------------------- | ---------------------------- |
| Float       | Detail view (slide-in) | Back button + Toggle button  |
| Custom      | Detail view (slide-in) | Back button + Toggle button  |
| Fullscreen  | Inline expansion       | Expand and collapse in place |

### Side panel visibility

The side panel appears when at least one of the following features is enabled:

* Custom header items
* Chat thread list (controlled by [`features.showThreadList`](customization_ui_configuration#features))
* Memory settings (controlled by [`features.showAgentMemory`](customization_ui_configuration#features))

### Itens ordering

Items render in the UI in the same order they are defined in the configuration array.

### Navigation structure

Supports a maximum two-level hierarchy (main menu and one submenu level). Deeper nesting is not supported.

### Responsive design

Custom header items dynamically migrate between the header and side panel based on container width:

| Viewport width | Breakpoint | Items in header | Items in side panel |
| -------------- | ---------- | --------------- | ------------------- |
| \< 320px       | xs         | 0               | All items           |
| 320px - 671px  | sm         | 1               | Remaining items     |
| 672px - 1055px | md         | 2               | Remaining items     |
| ≥ 1056px       | lg/xl/max  | 3 (maximum)     | Remaining items     |

<Note>The chat component uses a responsive layout with an optional side panel for rendering the chat thread list and custom header content. When implementing a custom layout, ensure the chat container height is at least 510px. In narrower viewports, the side panel collapses and the threads list container may not be rendered as expected.</Note>

**Example scenarios:**

* 5 custom items at 1200px width: 3 in header, 2 in side panel
* 5 custom items at 800px width: 2 in header, 3 in side panel
* 5 custom items at 400px width: 1 in header, 4 in side panel
* 5 custom items at 280px width: 0 in header, 5 in side panel

<Card title="Do you need practical examples?" icon="text-align-start" href="https://www.ibm.com/docs/SSAVQO/deploy/web_chat_agent/tutorials/tutorials_lp.html" arrow="true" cta="Learn with walk-throughs" horizontal>
  Learn how to apply the features available for embedded chat into your implementation with guidance and examples.
</Card>