Styling Your Assistant

Opening the Assistant From Your Own Button

By default the assistant opens from a round floating button in the bottom-right corner. You can open it from any element on your page instead, such as a button next to your search bar, a link in your navigation or an "Ask about this product" button.

Use these standard methods on HawkAI.Assistant:

MethodWhat it does
toggle()Opens the assistant if it's closed, closes it if it's open.
toggle(true) / toggle(false)Opens or closes it.
sendMessage('text')Opens the assistant and asks the question for the shopper.
<button type="button" id="ask-ai">Ask AI</button>

<script>
  document.getElementById('ask-ai').addEventListener('click', () => {
    HawkAI.Assistant.toggle();
  });
</script>

Asking a question for the shopper

sendMessage() opens the assistant and submits a question in one step. Use it for buttons such as "Ask about this product" or suggested questions on a page:

<button type="button" data-ask="Show me waterproof hiking boots">Waterproof boots</button>

<script>
  document.querySelectorAll('[data-ask]').forEach((button) => {
    button.addEventListener('click', () => HawkAI.Assistant.sendMessage(button.dataset.ask));
  });
</script>

Keeping your button in sync

The assistant can also be closed by its own buttons or the Escape key. Listen for the hawkai-assistant:open-changed event to keep your button's state (styling, aria-expanded) correct:

const askButton = document.getElementById('ask-ai');

window.addEventListener('hawkai-assistant:open-changed', (event) => {
  askButton.setAttribute('aria-expanded', String(event.detail.open));
});
🚧

The assistant can reopen itself on page load

If the shopper already has a conversation, the assistant opens automatically when the next page loads. open-changed doesn't fire for this, so your button may show "closed" while the window is open. The next click still works: toggle() with no argument flips whatever the real state is.

Hiding the floating button

When your own button opens the assistant, you'll usually want to hide the floating one. The assistant runs inside a Shadow DOM, so your site's CSS can't reach it. Pass the CSS through the ui.styles option instead:

HawkAI.Assistant.initialize({
  apiUrl: '...',
  accountId: '...',
  agentId: '...',
  ui: {
    styles: '.hawkai-assistant__trigger { display: none; }',
  },
});

Hiding it is optional. Leave the rule out and both your button and the floating button open the assistant.

Adding a close button

In the window layout, the floating button is also what closes the assistant. There's no X in the window's header, so the shopper can close it only with the Escape key or by clicking your button again. Add a close button to the header with the standard headerButtons option:

HawkAI.Assistant.initialize({
  // ...
  headerButtons: [
    {
      id: 'close',
      ariaLabel: 'Close assistant',
      className: 'my-close-button',
      icon: Object.assign(document.createElement('span'), {
        innerHTML: '<svg viewBox="0 0 24 24" width="20" height="20" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><path d="M6 6l12 12M18 6L6 18"/></svg>',
      }),
      onClick: () => HawkAI.Assistant.toggle(false),
    },
  ],
  ui: {
    styles: `
      .hawkai-assistant__trigger { display: none; }
      .my-close-button { order: 1; } /* custom buttons come first; move the X to the end */
    `,
  },
});

The drawer layout already has its own X, so it doesn't need this.

Moving the Assistant Window

Built-in options

These need no custom code:

OptionValuesResult
ui.position'right' (default), 'left'Which side of the screen the button and window use.
ui.display'window' (default)A floating card above the floating button.
'drawer'A full-height panel along the left or right edge.
'embedded'An always-visible panel inside an element on your page (ui.embedHostSelector). No floating button.

Placing the window anywhere with CSS

To put the window somewhere else, for example dropping down below a button in your header, override its position in ui.styles. The window is position: fixed, so you place it relative to the browser window with top, right, bottom, left and height. No JavaScript overrides are needed.

HawkAI.Assistant.initialize({
  apiUrl: '...',
  accountId: '...',
  agentId: '...',
  ui: {
    display: 'window',
    styles: `
      .hawkai-assistant__trigger { display: none; }

      /* Drop the window down below a 76px-tall header, lined up with a 1200px-wide page. */
      .hawkai-assistant__window--window:not(.hawkai-assistant__window--fullscreen) {
        top: 84px;
        bottom: auto;
        right: max(16px, calc((100% - 1200px) / 2 + 24px));
        left: auto;
        height: min(640px, calc(100dvh - 100px));
        max-height: none;
      }

      /* Phones: full width under the header. */
      @media (max-width: 639px) {
        .hawkai-assistant__window--window:not(.hawkai-assistant__window--fullscreen) {
          top: 72px;
          left: 8px;
          right: 8px;
          bottom: 8px;
          height: auto;
        }
      }
    `,
  },
});

Tips:

  • Always add :not(.hawkai-assistant__window--fullscreen). Without it, your position rules also apply in full-screen mode and stop it filling the screen.
  • Your rules take priority over the built-in ones. The assistant's own styles sit in a lower-priority CSS layer, so you don't need !important.
  • Your page's CSS variables work inside ui.styles. If your header height is in a variable such as --header-h, use top: calc(var(--header-h) + 8px) and the window follows your layout.
  • Use 100%, not 100vw, for horizontal maths. For a fixed element, 100% is the visible page width; 100vw includes the scrollbar and leaves the window a few pixels off.
  • Keeping the floating button too? On phones, stop the window above it (bottom: 96px) so the window doesn't cover it.
  • The window sits at z-index: 50. Keep sticky headers and other overlays below that, or raise the window's z-index in ui.styles.
  • The stable class names are listed under Custom Styling. The window's modifier classes are hawkai-assistant__window--window, --drawer, --embedded, --left, --right and --fullscreen.
📘

What can't be done with CSS

CSS fixes the window's position on the screen. If the window has to follow an element that moves when the page scrolls (for example, a search bar that isn't in a sticky header), use display: 'embedded' instead (below). Don't try to change the widget's JavaScript.

Alternative: embed it in your own panel

With display: 'embedded', the assistant fills an element you choose. Put that element wherever you want (a dropdown under your search bar, a sidebar, a tab) and show or hide it yourself:

<div id="assistant-panel" hidden style="height: 600px"></div>

<script>
  HawkAI.Assistant.initialize({
    apiUrl: '...',
    accountId: '...',
    agentId: '...',
    ui: {
      display: 'embedded',
      embedHostSelector: '#assistant-panel',
    },
  });

  document.getElementById('ask-ai').addEventListener('click', () => {
    const panel = document.getElementById('assistant-panel');
    panel.hidden = !panel.hidden;
  });
</script>

Things to know about embedded mode:

  • The element must have its own height. The assistant fills it.
  • toggle() and ui.open have no effect, and open-changed doesn't fire. You control visibility.
  • There's no close button. Add one with headerButtons that hides your element.
  • sendMessage() still works, but it won't make a hidden element visible. Show the element first.

Example: Assistant Button Next to the Search Bar

Live demo uses the Outdoor Demo store with nothing but standard options:

  • An Ask AI button next to the search bar opens and closes the assistant. (Search itself is turned off in the demo.)
  • Suggested-question buttons on the page use sendMessage().
  • The floating button is hidden, and the window drops down below the header.
  • A close (X) button is added with headerButtons.
  • Options on the page show the floating button again and move the window back to the bottom-right corner, so you can compare each setup. Changing an option reloads the page, because the assistant's settings are fixed once initialize() runs.

The demo's default setup (floating button hidden, window below Ask AI):

<script src="https://cdn.jsdelivr.net/npm/@bridgeline-digital/hawkai-assistant/dist/hawkai-assistant.js"></script>
<script>
HawkAI.Assistant.initialize({
  apiUrl: 'https://assistant-prod.hawksearch.net',
  accountId: 'e3141',
  agentId: '428bea83-cd00-449b-a025-a7d67fb6f689',
  headerButtons: [
    {
      id: 'close',
      ariaLabel: 'Close assistant',
      className: 'my-close-button',
      icon: Object.assign(document.createElement('span'), {
        innerHTML: '<svg viewBox="0 0 24 24" width="20" height="20" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><path d="M6 6l12 12M18 6L6 18"/></svg>',
      }),
      onClick: () => HawkAI.Assistant.toggle(false),
    },
  ],
  ui: {
    display: 'window',
    position: 'right',
    open: false,
    styles: `
      .hawkai-assistant__trigger { display: none; }
      .my-close-button { order: 1; }

      .hawkai-assistant__window--window:not(.hawkai-assistant__window--fullscreen) {
        top: calc(var(--header-h, 76px) + 8px);
        bottom: auto;
        right: max(16px, calc((100% - 1200px) / 2 + 24px));
        left: auto;
        height: min(640px, calc(100dvh - var(--header-h, 76px) - 24px));
        max-height: none;
      }

      @media (max-width: 639px) {
        .hawkai-assistant__window--window:not(.hawkai-assistant__window--fullscreen) {
          top: calc(var(--header-h, 64px) + 8px);
          left: 8px;
          right: 8px;
          bottom: 8px;
          height: auto;
        }
      }
    `,
  },
});

const askButton = document.getElementById('assistant-btn');

askButton.addEventListener('click', () => {
  HawkAI.Assistant.toggle();
});

document.querySelectorAll('[data-ask]').forEach((button) => {
  button.addEventListener('click', () => HawkAI.Assistant.sendMessage(button.dataset.ask));
});

window.addEventListener('hawkai-assistant:open-changed', (event) => {
  askButton.setAttribute('aria-expanded', String(event.detail.open));
});
</script>
📘

Embed settings override the dashboard

Anything in ui takes priority over the assistant's configuration screen. The Outdoor Demo assistant is configured as a left-side drawer that starts open. The demo sets display: 'window', position: 'right' and open: false to change that. The heading, logo, colors and prompt buttons still come from the dashboard.


Did this page help you?