Skip to main content
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

instance.updateCustomHeaderItems(items);

​
Parameters

​
items
array
required
An array of custom header items to display. Each item is an object that defines the properties of the header element.

​
items properties

​
id
string
required
A unique identifier for the header item.
​
text
array
required
The text to display for the header item.
​
align
string
The alignment of the header item. Possible values: left (default) or right.
​
icon
string
A URL or data URI to an icon image to display alongside the text.
​
type
string
required
The type of header item. Possible values: menu-item or dropdown. Default: menu-item.
​
onClick
function
A callback function called when the button is clicked. Required for menu-item type.
​
items
array
An array of submenu items for the dropdown. Required for dropdown type. |
​
showSelectedAsTitle
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.

​
Layout compatibility

fullscreen-overlayfloatcustom
showSelectedAsTitle
​
id
string
required
A unique identifier for the submenu item.
​
text
string
required
The text to display for the submenu item.
​
align
string
The alignment of the submenu item. Possible values: left (default) or right.
​
icon
string
A URL or data URI to an icon image to display alongside the submenu item text.
​
onClick
function
required
A callback function called when the submenu item is clicked.

​
Returns

​
void
Returns a void operator.

​
Examples

The following example creates a help button as menu item: 
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: 
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”: 
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. 
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 items behave differently based on form layout:
Form layoutDropdown behaviorNavigation pattern
FloatDetail view (slide-in)Back button + Toggle button
CustomDetail view (slide-in)Back button + Toggle button
FullscreenInline expansionExpand and collapse in place

​
Side panel visibility

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

​
Itens ordering

Items render in the UI in the same order they are defined in the configuration array. 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 widthBreakpointItems in headerItems in side panel
< 320pxxs0All items
320px - 671pxsm1Remaining items
672px - 1055pxmd2Remaining items
≥ 1056pxlg/xl/max3 (maximum)Remaining items
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.
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

Do you need practical examples?

Learn how to apply the features available for embedded chat into your implementation with guidance and examples.