Search bar

When a shopper submits a search, the widget opens and answers it: the search text becomes the shopper's first message, instead of a results page. Two methods connect a search to the widget:

• The HTML class: add just-ai_search_bar to the search <form> of a Shopify theme. No script to write.
• JavaScript: dispatch the just:ai-agent:open event from your own code, for a custom theme, a headless storefront, or a search the theme handles in script.

You can also follow the setup from the dashboard, under Surfaces → Search bar: it gives a test link for the theme you edit and a message ready to send to your developer.

Before you start

• The widget is active on the theme you edit. Complete the Shopify installation first. Without the widget, a search runs as usual and nothing opens.
• Work on a copy of your live theme. Duplicate it in Shopify, edit the copy, test it, then publish it.

How it works

The widget listens to every form submit on the page. When the submitted form carries the class just-ai_search_bar and contains an <input name="q">, the widget:

1. cancels the submit, so the browser stays on the page;
2. opens the chat panel;
3. sends the trimmed value of q as the shopper's first message. An empty search opens the panel with no message.

The conversation is recorded with the source search_bar, so you find it under Search bar in the dashboard's conversations.

The class never breaks the theme's search. The form submits normally to the search page whenever the widget cannot answer:

• the widget has not finished loading on the page;
• the store is in Preview and the browser did not open the test link;
• the store's plan has no conversations left.

Method 1: the HTML class

<!-- Before -->
<form
  action="{{ routes.search_url }}"
  method="get"
  role="search"
  class="search search-modal__form"
>
  <input
    class="search__input field__input"
    id="Search-In-Modal"
    type="search"
    name="q"
  />
  …
</form>

<!-- After -->
<form
  action="{{ routes.search_url }}"
  method="get"
  role="search"
  class="search search-modal__form just-ai_search_bar"
>
  <input
    class="search__input field__input"
    id="Search-In-Modal"
    type="search"
    name="q"
  />
  …
</form>

Themes that handle Enter in script

The class acts on the form's submit. Some predictive search dialogs take over Enter in their own script once suggestions are showing, and go to the search page themselves.

Horizon's header dialog (snippets/search-modal.liquid, script assets/predictive-search.js) is one of them. With the class on its form, Enter opens the widget only while no suggestion is showing yet. Once suggestions appear, Enter opens the search page, and only the button that shows all results still opens the widget. On Horizon and on themes built the same way:

• add the class to the search results page form (blocks/_search-input.liquid on Horizon), which submits normally;
• for the header dialog, take over Enter with the JavaScript method.

To spot such a dialog, type a search in it on the preview, wait for the suggestions, then press Enter: if the search page opens, its script handles Enter.

Method 2: JavaScript

Dispatch just:ai-agent:open on window, with the search as message and search_bar as source:

window.dispatchEvent(
  new CustomEvent('just:ai-agent:open', {
    detail: { message: query, source: 'search_bar' },
  }),
);

• message: the search text. It is sent as the shopper's first message as soon as the session is ready. Leave it empty to open the panel only.
• source: keep search_bar. It records the conversation as a search bar conversation in the dashboard.

An event dispatched while the widget is still loading is kept and replayed once it is ready. Only the latest early event is kept.

Connect a custom search form

For a custom theme or a search form you render yourself:

<form id="site-search" action="/search" method="get" role="search">
  <input type="search" name="q" aria-label="Search" />
  <button type="submit">Search</button>
</form>

<script>
  function openWidget(query) {
    window.dispatchEvent(
      new CustomEvent('just:ai-agent:open', {
        detail: { message: query, source: 'search_bar' },
      }),
    );
  }

  const form = document.getElementById('site-search');

  form.addEventListener('submit', (event) => {
    if (!customElements.get('just-ai-agent')) return;

    event.preventDefault();

    openWidget(form.elements.q.value.trim());
  });
</script>

Headless storefronts

The same event works in any framework. In React, for example:

function SearchForm() {
  function onSubmit(event: React.FormEvent<HTMLFormElement>) {
    if (!customElements.get('just-ai-agent')) return;

    event.preventDefault();

    const query = new FormData(event.currentTarget).get('q');

    window.dispatchEvent(
      new CustomEvent('just:ai-agent:open', {
        detail: { message: String(query ?? '').trim(), source: 'search_bar' },
      }),
    );
  }

  return (
    <form action="/search" role="search" onSubmit={onSubmit}>
      <input type="search" name="q" aria-label="Search" />
    </form>
  );
}

The widget must be installed on the storefront: see the headless installation.

Take over Enter in a predictive search dialog

For a dialog whose script handles Enter, listen to keydown on the document in the capture phase, so your listener runs before the theme's. This example acts on forms that carry the class, and leaves Enter to the theme when the shopper has selected a suggestion with the arrow keys:

document.addEventListener(
  'keydown',
  (event) => {
    if (event.key !== 'Enter' || event.isComposing) return;

    const input = event.target;

    if (!(input instanceof HTMLInputElement) || input.name !== 'q') return;

    const form = input.closest('form.just-ai_search_bar');

    if (!form || form.querySelector('[aria-selected="true"]')) return;

    if (!customElements.get('just-ai-agent')) return;

    event.preventDefault();
    event.stopPropagation();

    window.dispatchEvent(
      new CustomEvent('just:ai-agent:open', {
        detail: { message: input.value.trim(), source: 'search_bar' },
      }),
    );
  },
  true,
);

Themes differ in how they mark the selected suggestion: check yours and adapt the selector, then test every key path on the preview.

Test it

Open the store with the test link from the dashboard (Surfaces → Search bar). It carries two parameters:

• just_ai_tester=1 marks your browser as a test browser. While the store is in Preview, the widget loads only in a marked browser, and the conversations you start there count as tests, not as shoppers.
• preview_theme_id=… opens the theme copy you edit, when it is not your live theme.

You can also build it by hand: https://your-store.com/?preview_theme_id=123456789&just_ai_tester=1.

On that page, check each search form:

1. Type a search, then press Enter. The chat panel opens with your search as the first message, and the page does not move to /search.
2. Do the same with the search button, on desktop and on mobile.
3. Submit an empty search: the panel opens with no message.

To count the marked forms, run this in the browser console:

document.querySelectorAll('form.just-ai_search_bar').length;

Limits and troubleshooting

Going further

• Events reference: the full just:ai-agent:open contract.
• Trigger button: open the widget from any button or link.
• Analytics: the metrics behind the search_bar source.