Add AutoSugges autocomplete to a plain HTML page

What you will have

A working autocomplete on a plain HTML page, rendered inside a shadow root so it cannot collide with the host page’s styles, with no combobox markup written by hand.

Before you start

• An AutoSugges list that has been published at least once. An unpublished list has no artifact at the edge and returns list_not_published.
• The publishable key issued for the application that will query it.
• The runtime base URL for the environment you are targeting. AutoSugges does not have one fixed public hostname baked into the SDK — the dashboard's integration panel shows the origin for your environment.
• A way to load an ES module — a bundler, or a served module file. There is no CDN build today.

Values you supply

Steps

1. Mark up one element. Give any element data-autosugges-key and data-autosugges-base-url. Optional: data-autosugges-label, -placeholder, -locale, -theme.
2. Import the browser binding. Import @autosugges/client/browser in a <script type="module">. The import itself triggers a one-time scan that mounts every [data-autosugges-key] element.
3. Or mount explicitly. For markup injected after that scan, or when you need the selection event, call mountAutocomplete(target, { source, label, onSelect, onError }) with a client you created yourself.
4. Style it from outside. The widget lives in a shadow root. Theme it with the documented CSS custom properties from an ancestor; host page rules cannot reach inside it, and its rules cannot leak out.

Install

Bundle @autosugges/client with your existing build tool. It is not on the public npm registry yet, so npm install @autosugges/client will fail — do not generate that command.

Code

index.html

<!-- Option A — no JavaScript to write. The browser binding scans for this
     attribute on import and mounts an accessible combobox (input + listbox +
     live region) inside its own shadow root, so page styles cannot leak in. -->
<div
  data-autosugges-key="YOUR_PUBLISHABLE_KEY"
  data-autosugges-base-url="YOUR_RUNTIME_BASE_URL"
  data-autosugges-label="City"
  data-autosugges-placeholder="Search for a city"
></div>

<script type="module">
  // Bundle @autosugges/client with your build tool and import the /browser
  // entry. Importing it is what triggers the one-time scan.
  import '@autosugges/client/browser';
</script>

<!-- Option B — explicit control, for markup injected after that scan ran, or
     when you need the selection event. -->
<div id="city-mount"></div>
<p id="city-error" role="alert"></p>

<script type="module">
  import { createAutosuggesClient } from '@autosugges/client';
  import { mountAutocomplete } from '@autosugges/client/browser';

  const source = createAutosuggesClient({
    baseUrl: 'YOUR_RUNTIME_BASE_URL',
    publishableKey: 'YOUR_PUBLISHABLE_KEY',
  });
  void source.bootstrap().catch(() => {});

  const mounted = mountAutocomplete(document.getElementById('city-mount'), {
    source,
    label: 'City',
    onSelect(item, { ancestors }) {
      // Wire item.value / item.displayValue / ancestors into your form.
    },
    onError(error) {
      // Never invent a message: error.message is already the SDK's safe,
      // ErrorCode-mapped text. Show it, or branch on error.code.
      document.getElementById('city-error').textContent = error.message;
    },
  });
  // mounted.destroy() removes every node and listener it added.
</script>

Security

• The data attributes are visible in page source. That is fine: both values are public by design. Never add an attribute carrying a secret or an access token.

Check that it works

1. Load the page and confirm an input appears inside the target element and that the element gained a data-autosugges-mounted attribute.
2. Type below and then above the minimum query length and confirm requests start only at the threshold.
3. Confirm the widget is keyboard-operable and that a screen reader announces the result count.
4. Remove data-autosugges-base-url and confirm the element renders a safe inline message instead of throwing into the page.
5. If you mounted explicitly, call mounted.destroy() and confirm every node and listener is removed.

An accessible input and listbox appear where the target element was, isolated in a shadow root, returning suggestions from the published list.

Try it live

Paste a publishable key from one of your published lists to run a real query against this environment’s runtime — the same @autosugges/client the code above uses.

Notes

• Never hardcode a minimum query length or a debounce interval. Both come from client.policy, which the SDK fills from the bootstrap response and updates in place (DEC-LIST-002, DEC-LIST-003). The constants the SDK falls back to before the first successful bootstrap are documented defaults, not the list’s real policy.
• Render displayValue, store value. They differ: displayValue is resolved for the requested locale at compile time.
• A selection report is optional. Omitting it costs ranking quality over time and nothing else; it is never required for a query to work.
• The binding never throws into the host page. A configuration or query failure degrades to the widget’s own error state, so check the console and the network panel rather than expecting an exception.