Widget customization

Configure the assistant and search widgets by setting HTML attributes. Override text properties to localize the widget.

biel-button

The <biel-button> component adds a floating AI chat button to your site. Use <biel-bot> to render the same assistant inline; it accepts the assistant modal properties below. See Embedded mode.

Usage

<biel-button project="YOUR_PROJECT_ID" header-title="Biel.ai assistant" button-style="dark">Ask AI</biel-button>

Assistant button properties

Property	Description
Layout
project	Required Type: string The project ID.
button-position	Type: string Default value: default Available values: default, bottom-right, bottom-left, center-right, center-left, custom Controls the position of the chat button on your webpage. Use custom to position the button using CSS.
button-style	Type: string Default value: default Available values: default, dark, light Defines the visual style of the chat button. dark and light choose a launcher palette; default inherits the page styling. The modal theme is controlled separately by data-theme.
custom-font	Type: boolean Default value: false When set to true, disables loading of the Inter font. Use this if your site already uses a different font to improve load time and maintain font consistency.
hide-icon	Type: boolean Default value: false When set to true, the button icon hides.
ai-icon	Type: string Default value: biel Available values: biel, bot, sparks, question-mark Specifies which AI icon to display in the button.
hide-avatars	Type: boolean Default value: false When set to true, hides avatars in the chat interface.
api-key	Type: string Default value: `` API key for authenticating requests to private projects. Required for private projects with chat_create and project_read permissions. Not required for public projects.
api-url	Type: string Default value: Biel.ai API Override the base API URL for self-hosted or custom endpoints.

The "Powered by Biel.ai" branding is controlled by your team's Remove 'Powered by Biel.ai' branding setting. An eligible plan enables that setting; you still need to activate it and click Save details. See Whitelabel.

Assistant modal properties

Property	Description
Layout
disable-input	Type: boolean Default value: false When set to true, the user input field is disabled.
disable-autofocus	Type: boolean Default value: false When set to true, opening the assistant does not focus the message input automatically.
email	Type: string Default value: `` An email address or ID for conversation tracking. This ID will be associated with the chat session in your project dashboard for analytics and user tracking purposes.
metadata	Type: string Default value: `` Custom metadata to attach to chat sessions. Use this to pass additional contextual information (e.g., user plan, page URL, or other identifiers) that will be associated with the conversation for analytics purposes.
expand-modal	Type: boolean Default value: false When set to true, the chat modal opens in its expanded state by default.
hide-close-button	Type: boolean Default value: false When set to true, the close icon hides.
hide-expand-button	Type: boolean Default value: false When set to true, the expand button icon hides.
hide-refresh-button	Type: boolean Default value: false When set to true, the refresh button hides.
hide-feedback	Type: boolean Default value: false When set to true, removes the feedback options (like thumbs up/down) that users can use to rate AI responses.
hide-sources	Type: boolean Default value: false When set to true, hides the sources section from AI responses in the chat interface.
hide-inline-citations	Type: boolean Default value: false When set to true, removes numeric inline citations from AI answers and their numbers from source cards. The sources section remains available unless hide-sources is also set.
hide-settings-button	Type: boolean Default value: false When set to true, hides the reasoning mode selector above the message input. Only applies if reasoning mode is enabled for your project.
hide-connect-button	Type: boolean Default value: false When set to true, hides the Connect menu above the message input. This menu provides MCP (Model Context Protocol) connection options when MCP is enabled for the project.
hide-tooltips	Type: boolean Default value: false When set to true, hides the tooltips that appear when hovering over header icons.
loading-indicator	Type: string Default value: spinner Available values: spinner, dots Shows a spinner with the current operation while the assistant is working. Use dots for the previous bouncing dots animation without visible progress text. Screen reader announcements and error recovery remain available. See Chat progress.
loading-text	Type: string Default value: Loading… Loading label before the first progress update arrives. With dots, this label is announced to screen readers without appearing visually. See Chat progress.
modal-position	Type: string Default value: center Available values: center, top-center, top-left, top-right, center-left, center-right, bottom-left, bottom-right, sidebar-left, sidebar-right Determines where the chat modal appears on the screen when opened. Use sidebar-left or sidebar-right to dock the chat as a side panel.
show-terms-modal	Type: boolean Default value: false When set to true, displays a terms and conditions modal before starting the chat.
think-mode-enabled	Type: boolean Default value: false Legacy option that starts a new conversation in Think mode when reasoning mode is enabled for the project. Use default-think-mode to choose Auto, Instant, or Think. A visitor's saved choice takes precedence. See Reasoning modes.
default-think-mode	Type: string Available values: auto, fast, think Starting mode for a new conversation when reasoning mode is enabled for the project. A visitor's saved choice takes precedence. This property takes precedence over the legacy think-mode-enabled option. See Reasoning modes.
keep-conversation	Type: boolean Default value: true When set to false, clears the conversation history on page navigation. By default, a conversation can be restored across page reloads for one hour after its last saved update, using browser storage. Each widget instance keeps its own conversation; use a stable HTML id when placing several widgets on a page.
render-math	Type: boolean Default value: true When set to true, typesets supported LaTeX in AI answers with MathJax. Set to false to leave LaTeX source unchanged.
render-diagrams	Type: boolean Default value: true Renders Mermaid diagrams in AI answers. Set to false to show their source code instead.
mermaid-theme	Type: string Default value: default Theme used for rendered Mermaid diagrams.
mathjax-url	Type: string Default value: https://cdn.jsdelivr.net/npm/[email protected]/es5/tex-svg.js The MathJax script URL. Set this to a self-hosted copy when your site's Content Security Policy blocks the default CDN.
MCP Integration
mcp-server-url	Type: string Default value: `` Override the MCP server URL. Use for custom or self-hosted MCP servers, or when authentication is required. Takes priority over the API-provided URL. See MCP Server.
Text
assistant-label	Type: string Default value: Assistant Label text displayed above AI responses in the chat.
close-button-text	Type: string Default value: Close Tooltip text for the close button in the assistant header.
collapse-button-text	Type: string Default value: Collapse Tooltip text for the collapse button in the assistant header.
error-message-4-0-3	Type: string Default value: Oops! The request URL or API key is invalid or not authorized for this project. 403 unauthorized message.
error-message-4-0-4	Type: string Default value: Oops! We could not find the provided project ID. 404 not found message.
error-message-default	Type: string Default value: Oops! Please try again later. 500 error message.
expand-button-text	Type: string Default value: Expand Tooltip text for the expand button in the assistant header.
footer-text	Type: string Default value: AI answers may be inaccurate. Verify with official sources. Footer text.
header-title	Type: string Default value: Company Name AI Title text for the assistant header.
input-placeholder-text	Type: string Default value: Type your message Placeholder text displayed in the assistant's input field.
connect-button-text	Type: string Default value: Connect Tooltip text for the Connect button in the assistant header.
mcp-url-text	Type: string Default value: MCP URL Label for the MCP URL option in the connect dialog.
mcp-url-description	Type: string Default value: Copy to clipboard Description text for the MCP URL option in the connect dialog.
mcp-claude-text	Type: string Default value: Claude Code Label for the Claude Code option in the connect dialog.
mcp-claude-description	Type: string Default value: CLI command Description text for the Claude Code option in the connect dialog.
mcp-codex-text	Type: string Default value: Codex Label for the Codex option in the Connect menu.
mcp-codex-description	Type: string Default value: Copy setup command Tooltip text for copying the Codex setup command.
mcp-codex-copied-description	Type: string Default value: Command copied to clipboard Confirmation after copying the Codex setup command.
mcp-copilot-text	Type: string Default value: Copilot (VS code) Label for the Copilot option in the connect dialog.
mcp-copilot-description	Type: string Default value: Opens in a new tab Description text for the Copilot option in the connect dialog.
mcp-cursor-text	Type: string Default value: Cursor Label for the Cursor option in the connect dialog.
mcp-cursor-description	Type: string Default value: Opens in a new tab Description text for the Cursor option in the connect dialog.
mcp-copied-text	Type: string Default value: Copied! Confirmation text shown after copying an MCP value to the clipboard.
mcp-url-copied-description	Type: string Default value: URL copied to clipboard Description text shown after copying the MCP URL.
mcp-claude-copied-description	Type: string Default value: Command copied to clipboard Description text shown after copying the Claude Code command.
refresh-button-text	Type: string Default value: Refresh Tooltip text for the refresh button in the assistant header.
continue-text	Type: string Default value: Continue generating Label for continuing an answer that reached its length limit.
incomplete-text	Type: string Default value: This answer could not be completed. Ask for a shorter answer or a specific section. Message shown when an answer cannot be completed.
message-too-long-text	Type: string Default value: Message is too long. Use at most 10,000 characters. Validation message for an oversized question.
send-button-text	Type: string Default value: Send Text displayed on the send button next to the input field.
sources-text	Type: string Default value: Sources Text displayed for introducing sources in messages.
suggested-questions	Type: string Default value: empty A JSON array or comma-separated list of questions shown when users open the chat. For example, suggested-questions='["How do I start?", "What can I build?"]'.
suggested-questions-title	Type: string Default value: Suggested questions The heading text that appears above the list of suggested questions in the chat interface.
settings-button-text	Type: string Default value: Settings Tooltip text for the settings button (reasoning mode selector) in the assistant header. Only visible if reasoning mode is enabled for your project.
terms-checkbox-text	Type: string Default value: I have read and agree to the Terms & Conditions. Text displayed next to the terms acceptance checkbox.
terms-description	Type: string Default value: Please review our <a href='https://biel.ai/terms' target='_blank' rel='noopener'>Terms & Conditions</a> before proceeding. Description text shown in the terms and conditions modal.
terms-title	Type: string Default value: Chatbot Terms & Conditions Title text for the terms and conditions modal.
think-mode-auto-text	Type: string Default value: Auto Label for the Auto reasoning mode in the settings dropdown.
think-mode-auto-description	Type: string Default value: Balances speed and quality Description for the Auto reasoning mode.
think-mode-fast-text	Type: string Default value: Instant Label for the Instant reasoning mode in the settings dropdown.
think-mode-fast-description	Type: string Default value: Prioritizes speed Description for the Instant reasoning mode.
think-mode-think-text	Type: string Default value: Think Label for the Think reasoning mode in the settings dropdown.
think-mode-think-description	Type: string Default value: Takes longer for better accuracy Description for the Think reasoning mode.
welcome-message	Type: string Default value: "" A custom greeting message that appears when users first open the chat.

The escape-close, click-outside-close, and show-modal properties are available on <biel-bot> directly. The <biel-button> launcher does not expose those properties.

When using <biel-bot> directly, you can also set smooth-streaming="false" to display response chunks as they arrive instead of smoothing their appearance. Its default is true.

biel-search-button

The <biel-search-button> component adds an AI-powered search bar to your site. Use <biel-search> to render the search interface directly; it accepts the search modal and assistant modal properties below.

Usage

<biel-search-button project="YOUR_PROJECT_ID" button-style="rounded" search-placeholder="Search here...">Search</biel-search-button>

Search button properties

Property	Description
Layout
project	Required Type: string The project ID.
button-style	Type: string Default value: default Available values: default, rounded Style of the button.
custom-font	Type: boolean Default value: false When set to true, the Inter font will not be loaded. Useful if your site already uses a different font, enabling a quicker load time.
hide-ctrl-k	Type: boolean Default value: false When set to true, hides the Ctrl+K hint and disables the launcher's Ctrl+K keyboard shortcut.
hide-icon	Type: boolean Default value: false When set to true, the button icon hides.
ai-icon	Type: string Default value: biel Available values: biel, bot, sparks, question-mark Specifies the AI icon in the assistant opened through Ask AI. The search launcher uses a search icon.
hide-avatars	Type: boolean Default value: false When set to true, hides avatars in the chat interface.
api-key	Type: string Default value: `` API key for authenticating requests to private projects. Required for private projects with chat_create, project_search, and project_read permissions. Not required for public projects.

Search modal properties

Property	Description
Layout
disable-autofocus	Type: boolean Default value: false When set to true, opening search does not focus the search input automatically.
hide-ask-ai-button	Type: boolean Default value: false When set to true, the "Ask AI" button is hidden from the search results.
hide-descriptions	Type: boolean Default value: false When set to true, hides descriptions in search results for a cleaner interface.
hide-filters	Type: boolean Default value: false When set to true, hides the site filter dropdown. The dropdown appears beside the navigation hints when search filters are configured in your project settings. See Search filters.
hide-navigation-buttons	Type: boolean Default value: false When set to true, hides navigation buttons (up and down arrows, enter, escape) in the search modal for a simplified interface.
modal-position	Type: string Default value: top-center Available values: center, top-center, top-left, top-right, center-left, center-right, bottom-left, bottom-right, sidebar-left, sidebar-right Position of the search modal. Use sidebar-left or sidebar-right to dock as a side panel.
stacked	Type: boolean Default value: false When set to true, displays search results in a stacked layout.
clean-titles	Type: boolean Default value: false When set to true, removes site names from page titles that follow the format "Page Title
Text
ai-result-fragment	Type: string Default value: "Ask AI to answer your question" Text displayed in the AI result section of the search modal.
all-sites-text	Type: string Default value: All sites Label for the unfiltered option in the site filter dropdown.
search-placeholder	Type: string Default value: "Search or ask AI..." Placeholder for the search input.

Search assistant modal properties

Most properties that can be defined in <biel-button> for configuring the assistant modal can be set in the biel-search-button.

For details, see Assistant modal properties. Diagram options (render-diagrams and mermaid-theme) are supported by <biel-button> and <biel-bot>; the search widgets do not expose them.

Use <biel-search> directly for escape-close, click-outside-close, and show-search-modal. These properties are not exposed by the <biel-search-button> launcher.

Common customizations

Change the assistant title

By default, the assistant header displays "Company Name AI". Set the header-title property to show your own title:

<biel-button project="YOUR_PROJECT_ID" header-title="Acme AI">Ask AI</biel-button>

Change the button text

Replace the inner text of the element to change what the button says:

<biel-button project="YOUR_PROJECT_ID">Help</biel-button>

Open the chat modal from a custom element

Use <biel-bot> directly and set its show-modal property from a custom button:

<biel-bot id="my-assistant" project="YOUR_PROJECT_ID"></biel-bot>
<button onclick="document.querySelector('#my-assistant').showModal = true">Ask AI</button>

Use the equivalent show-search-modal property on <biel-search> to open search programmatically. The two launcher components open their modals when clicked; assigning these modal properties to a launcher does not open its modal.