alpha

This version is in early development and is subject to change and therefore not ready for wide use. There may be other stable versions available.

Chatbot Modal container

The vf-chatbot-modal component appears as an overlay, typically in the bottom right corner of the screen. It is designed for contextual assistance, allowing users to receive support without navigating away from the current page.

github location npm version

Usage

When to use this component

Only use the chatbot modal if it truly enables it helps users:

  • Get quick, contextual help while staying focused on their main task
  • Access specific guidance (such as FAQs, form instructions or navigation tips) without leaving the current page
  • Complete short, task-oriented interactions with minimal disruption

For example, the modal works well during checkouts or while filling out complex forms, where users may need immediate support without losing their progress. Chatbot modals can also benefit users who are familiar with a service and want targeted help to speed up their work. Test with users to ensure the embedded assistance enhances rather than disrupts their workflow.

When not to use this component

The chatbot modal overlays the existing interface and may distract users or obscure important content. Not all users will notice the chatbot icon or understand when to interact with it.

Do not use the chatbot modal if the help content is essential for completing a task. Critical guidance should be directly visible in the interface.

Test your workflow without a chatbot first. Clear content, in-line guidance, and intuitive layout may negate the need for a modal.

It's usually better to:

  • Integrate support directly within the page or form
  • Display key information upfront, especially if it applies to all users
  • Use tooltips or inline help for very brief, contextual instructions
  • Direct users to a dedicated help page for complex support needs

Avoid putting the chatbot modal for help or multi-step interactions. These are better suited to a chatbot standalone experience or a well-structured support section.

Avoid placing modals over elements that users need to interact with, and never trigger the chatbot automatically without user intent.

Deciding between modal vs standalone

The chatbot modal and chatbot standalone are two distinct variants for delivering conversational interfaces. Choose between them based on use case needs and task complexity.

Modal

  • For in-context support (e.g. help with current page or workflow)
  • Access point is via a floating action button on the page
  • Supports simple tasks such as getting information

Standalone

  • Suitable for exploratory or focused workflows (e.g. discovering genetic variants)
  • Launched via a link (such as "Talk to our AI chat assistant")
  • Supports more complex tasks that benefit from sustained engagement

Anatomy

Element Description
Title bar Shows the chatbot name, minimise button and close button. The title bar may include a dropdown for selecting categories.
Dialogue section Scrollable chat window showing the conversation log.
Intro message A brief onboarding message explaining the purpose and capabilities of the chatbot. Shows the icon, title and short message (Max. 2 lines of text).
Banner Used to show optional disclaimers or alerts (Max. 3 lines of text). For cases that require user consent, use a blur overlay on the background or a pre-access popup instead, as banners may be missed.
Text input area Open input field for typing and sending queries. Expands up to 5 lines, after which it becomes scrollable.

Flows

Flow Details
Suggested prompts Appear on the initial screen. Provide a quick-start to users with clickable queries. They help to provide context on the type of questions the user can ask on the platform. (Max. 60 characters)
Closing the chat dialogue Clicking on the close icon "X" triggers a confirmation prompt to prevent accidental loss of the chat log.
Error management If the chatbot is unable to provide a response to the query, display a clear error message and provide an alternative way for them to get their answers.
Links Displayed in a clear underlined style. They can be shown inline or as a list.
Source attribution Chips are shown in relevant paragraphs which cite the sources. Links to the sources and more details can be accessed via a "View sources" button.
Feedback on a query level Users can assess the AI responses with a thumbs up/thumbs down or optional close/open response fields to give more details.
Category selection A dropdown in the title bar lets users switch focus areas (e.g LLM version or data source). Single or multi-selection variants can be used depending on the use case.

Accessibility

The component targets WCAG 2.1 AA accessibility standard.

Variants

Nunjucks syntax

Depending on your environment you'll want to use render or include. As a rule of thumb: server-side use include, precompiled browser use render. If you're using vf-eleventy you should use include.

Using include

You'll need to pass a context object from your code or Yaml file (example), as well as the path to the Nunjucks template. Nunjucks' include is an abstraction of render and provides some additional portability.


{% set context fromYourYamlFile %}
- or -
{% set context = { 
"component-type" : "container",
 }
%}
{% include "../path_to/vf-chatbot-modal/vf-chatbot-modal.njk" %}

Using render

This approach is best for bare-bones Nunjucks environments, such as precompiled templates with the Nunjucks slim runtime where include is not be available.


{% render '@vf-chatbot-modal', {
  "component-type" : "container",}
%}
HTML 
<!--
<div class="vf-chatbot-modal" data-vf-js-chatbot-modal>
  
    <div class="vf-chatbot-modal__header">
      <div class="vf-chatbot-modal__header-left">
        
      </div>
      <div class="vf-chatbot-modal__controls">
        <button
          class="vf-chatbot-modal__control"
          data-vf-js-chatbot-minimize
          aria-label="Minimize chat"
        >
          <svg width="24" height="24" viewBox="0 0 24 24">
            <path d="M20 14H4v-2h16v2z"/>
          </svg>
        </button>
        <button
          class="vf-chatbot-modal__control"
          data-vf-js-chatbot-close
          aria-label="Close chat"
        >
          <svg width="24" height="24" viewBox="0 0 24 24">
            <path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/>
          </svg>
        </button>
      </div>
    </div>

    <div class="vf-chatbot-modal__content | vf-u-background-color-ui--grey--light">
      <div class="vf-chatbot-modal__chat" data-vf-js-chatbot-modal-chat>
        
          <div class="vf-chatbot-modal__welcome" data-vf-js-chatbot-modal-welcome>
            <div class="vf-chatbot-modal__welcome-content">
              <div class="vf-chatbot-modal__welcome-logo">
                <img src="/assets/vf-chatbot/assets/vf-chatbot--icon-64x64-dark-green.svg" alt="AI Assistant">
              </div>
              <h2 class="vf-chatbot-modal__welcome-title">AI assistant</h2>
              <p class="vf-chatbot-modal__welcome-description">
                
              </p>

              <div class="vf-chatbot-modal__welcome-suggestions">
                <p class="vf-chatbot-modal__welcome-suggestions-title">Try asking me:</p>
                <div class="vf-chatbot-standalone__welcome-suggestions-grid" data-vf-js-chatbot-standalone-suggestions-grid>
                </div>
              </div>
            </div>
          </div>
          
        
        <div class="vf-chatbot-modal__messages" data-vf-js-chatbot-modal-messages>
          <div class="vf-chatbot-modal__loading" data-vf-js-chatbot-modal-loading style="display: none;">
            <div class="vf-chatbot-message vf-chatbot-message--assistant">
              <div class="vf-chatbot-message__avatar">
                <div class="vf-chatbot-message__avatar-image">
                <img src="../../assets/vf-chatbot/assets/vf-chatbot--icon-16x16-dark-green.svg" alt="AI Assistant">
                </div>
                <span class="vf-chatbot-message__avatar-name">AI Assistant</span>
              </div>
              <div class="vf-chatbot-modal__loading-dots">
                ...
              </div>
            </div>
          </div>
        </div>
      </div>

    </div>
      
        <div class="vf-chatbot-modal__disclaimer" data-vf-js-chatbot-modal-disclaimer>
          <div class="vf-banner vf-banner--alert vf-banner--info">
            <div class="vf-banner__content">
              <p class="vf-banner__text"></p>
              <button role="button" aria-label="close notification banner" class="vf-button vf-button--icon vf-button--dismiss | vf-banner__button" data-vf-js-chatbot-disclaimer-close>
                <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
                  <title>dismiss banner</title><path d="M14.3,12.179a.25.25,0,0,1,0-.354l9.263-9.262A1.5,1.5,0,0,0,21.439.442L12.177,9.7a.25.25,0,0,1-.354,0L2.561.442A1.5,1.5,0,0,0,.439,2.563L9.7,11.825a.25.25,0,0,1,0,.354L.439,21.442a1.5,1.5,0,0,0,2.122,2.121L11.823,14.3a.25.25,0,0,1,.354,0l9.262,9.263a1.5,1.5,0,0,0,2.122-2.121Z"/></svg>
              </button>
            </div>
          </div>
        </div>
      

      
      <div class="vf-chatbot-modal__input-container">
        <textarea
          class="vf-chatbot-modal__input"
          placeholder="Ask me ..."
          rows="1"
          data-vf-js-chatbot-modal-input
          maxlength="1000"
        ></textarea>
        <button
          class="vf-chatbot-modal__send-button"
          aria-label="Send message"
          data-vf-js-chatbot-modal-send
        >
          <svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
            <path d="M16.01 11H4v2h12.01v3L20 12l-3.99-4v3z" fill="white"/>
          </svg>
        </button>
      </div>
  
</div>-->

Examples

Changelog

Changelog

Assets


File system location: components/vf-chatbot-modal

Find an issue on this page? Propose a change or discuss it.