Auto Complete HDS
Examples
Label
Label Suffix
Minimum Search Characters
Clear Icon Slot
Help Text
Sizes
Placeholder
Prefix
Suffix
Max Results
Searching
No Results
Multi-Select
Multi-Select with Checkboxes
Tag Truncation
Dropdown Height
Input Minimum Width
Custom Item Rendering
Performance with Large Datasets
Backend Filtering
Single Select
Multi-Select
Multi-Select with Checkboxes
States
Disabled
Readonly
Required
Events
Reactivity
Setting Selected Items Programmatically
Keyboard Interaction
Slots
Properties
Events
Custom Properties
Parts
Dependencies

Auto Complete Hds

<sl-auto-complete-hds> | SlAutoCompleteHds

Since 1.0

experimental

Auto Complete Component

<sl-auto-complete-hds id="hero" label="Technology" placeholder="Try: Machine Learning"></sl-auto-complete-hds>
<script type="module">
  document.getElementById('hero').data = {
    categories: [],
    data: [
      { value: 'Artificial Intelligence' },
      { value: 'Machine Learning' },
      { value: 'Quantum Computing' },
      { value: 'Blockchain' },
      { value: 'Cloud Computing' },
      { value: 'Cybersecurity' }
    ]
  };
</script>

Examples

Label

Use the label attribute for plain text labels. For labels that contain HTML, use the label slot instead.

By default the label is placed above the input. Add the label-inline attribute to display the label inline with the input instead.

Label slot — supports HTML

<div style="display: flex; flex-flow: column; gap: 15px">
  <sl-auto-complete-hds label="Stacked label (default)"></sl-auto-complete-hds>
  <sl-auto-complete-hds label-inline label="Inline label"></sl-auto-complete-hds>
  <sl-auto-complete-hds>
    <label slot="label">Label slot — <strong>supports HTML</strong></label>
  </sl-auto-complete-hds>
</div>

Label Suffix

Add label-suffix to display a contextual tooltip icon next to the label. Useful for progressive disclosure of additional instructions.

<sl-auto-complete-hds label="Portfolio" label-suffix="Search by client name, account number, or product type."></sl-auto-complete-hds>

Minimum Search Characters

Use min-search-chars to delay opening/filtering until the user types a minimum number of characters.

<sl-auto-complete-hds
  id="min-search-chars-example"
  label="Technology"
  placeholder="Type at least 3 characters..."
  min-search-chars="3"
></sl-auto-complete-hds>

<script type="module">
  document.getElementById('min-search-chars-example').data = {
    categories: [],
    data: [
      { value: 'Artificial Intelligence' },
      { value: 'Machine Learning' },
      { value: 'Deep Learning' },
      { value: 'Natural Language Processing' },
      { value: 'Computer Vision' },
      { value: 'Cloud Computing' },
      { value: 'Cybersecurity' }
    ]
  };
</script>

Clear Icon Slot

Use the input-clear-icon slot to replace the default clear icon content.

Clear

<sl-auto-complete-hds id="clear-icon-example" label="Search" placeholder="Type to show clear control">
  <span slot="input-clear-icon" style="margin-right: 10px;">Clear</span>
</sl-auto-complete-hds>

<script type="module">
  document.getElementById('clear-icon-example').data = {
    categories: [],
    data: [{ value: 'Apple' }, { value: 'Banana' }, { value: 'Cherry' }]
  };
</script>

<style>
  sl-auto-complete-hds#clear-icon-example::part(auto-complete-hds--clear-button) {
    margin-right: var(--hds-space-2x);
  }
</style>

Help Text

Use help-text to provide supporting instructions beneath the input. For rich HTML help text, use the help-text slot.

Only showing active items.

<div style="display: flex; flex-flow: column; gap: 15px">
  <sl-auto-complete-hds label="Search" help-text="Start typing to see matching results."></sl-auto-complete-hds>
  <sl-auto-complete-hds label="Search">
    <span slot="help-text">Only showing <strong>active</strong> items.</span>
  </sl-auto-complete-hds>
</div>

Sizes

Three sizes are available: small, medium (default), and large. Heights are aligned with sl-input and sl-select.

<div style="display: flex; flex-flow: column; gap: 15px">
  <sl-auto-complete-hds size="small" label="Small"></sl-auto-complete-hds>
  <sl-auto-complete-hds label="Medium (default)"></sl-auto-complete-hds>
  <sl-auto-complete-hds size="large" label="Large"></sl-auto-complete-hds>
</div>

Placeholder

Use placeholder to give the user a hint about what to type. Always include a placeholder — it sets expectations and improves usability.

<sl-auto-complete-hds placeholder="Search by name or keyword..."></sl-auto-complete-hds>

Prefix

The prefix slot defaults to a magnifying-glass icon. Replace it with any icon or element.

<div style="display: flex; flex-flow: column; gap: 15px">
  <sl-auto-complete-hds label="Default prefix"></sl-auto-complete-hds>
  <sl-auto-complete-hds label="Custom prefix">
    <sl-icon slot="prefix" name="fas-user"></sl-icon>
  </sl-auto-complete-hds>
</div>

Suffix

Use the suffix slot to append content to the right side of the input — for example a spinner while data loads, or a status badge.

Checking

<sl-auto-complete-hds label="Account search">
  <div slot="suffix" style="display:flex;align-items:center;gap:5px">
    <span style="font-size:12px;color:#6b7280">Checking</span>
    <sl-spinner style="font-size:16px;--indicator-color:var(--hds-color-fg-subtlest,#6E7685)"></sl-spinner>
  </div>
</sl-auto-complete-hds>

Max Results

Use max-results to limit how many items are shown in the dropdown. Using 0 will set unlimited.

<sl-auto-complete-hds id="max-results-example" label="Technology" placeholder="Type to search..." max-results="3"></sl-auto-complete-hds>

<script type="module">
  document.getElementById('max-results-example').data = {
    categories: [],
    data: [
      { value: 'Artificial Intelligence' },
      { value: 'Machine Learning' },
      { value: 'Deep Learning' },
      { value: 'Natural Language Processing' },
      { value: 'Computer Vision' },
      { value: 'Cloud Computing' },
      { value: 'Cybersecurity' }
    ]
  };
</script>

Searching

The autocomplete filters items client-side as the user types, matching any part of the value and bolding matched characters. Categories group related items with a header and divider.

<div style="display: flex; flex-flow: column; gap: 15px">
  <sl-auto-complete-hds id="search-basic" label="Basic search" placeholder="Try: Machine"></sl-auto-complete-hds>
  <sl-auto-complete-hds id="search-categories" label="Search with categories" placeholder="Try: Intelligence"></sl-auto-complete-hds>
</div>

<script type="module">
  document.getElementById('search-basic').data = {
    categories: [],
    data: [
      { value: 'Artificial Intelligence' },
      { value: 'Quantum Computing' },
      { value: 'Machine Learning' },
      { value: 'Blockchain' },
      { value: 'Cloud Computing' },
      { value: 'Cybersecurity' }
    ]
  };

  document.getElementById('search-categories').data = {
    categories: [
      { id: 1, category: 'Technology' },
      { id: 2, category: 'Science' }
    ],
    data: [
      { value: 'Artificial Intelligence', categoryId: 1 },
      { value: 'Machine Learning', categoryId: 1 },
      { value: 'Blockchain', categoryId: 1 },
      { value: 'Quantum Computing', categoryId: 2 },
      { value: 'Bioinformatics', categoryId: 2 },
      { value: 'Other Topic' }
    ]
  };
</script>

No Results

When no items match the search string, the component shows a no-results message. Customise the text with the no-results-text attribute. The user can also click the inline link to clear the input and search again.

<sl-auto-complete-hds

  id="no-results-example"
  label="Search"
  placeholder="Try typing something obscure"
  no-results-text="No matching items found. Try a different search term."
></sl-auto-complete-hds>

<script type="module">
  document.getElementById('no-results-example').data = {
    categories: [],
    data: [
      { value: 'Artificial Intelligence' },
      { value: 'Quantum Computing' },
      { value: 'Machine Learning' }
    ]
  };
</script>

Multi-Select

Add multi-select to allow selecting more than one item. Selected items appear as removable tags inside the input. Already-selected items are automatically removed from the dropdown list.

<sl-auto-complete-hds multi-select id="multi-select-example" label="Technologies" placeholder="Type to search..."></sl-auto-complete-hds>

<script type="module">
  document.getElementById('multi-select-example').data = {
    categories: [],
    data: [
      { value: 'Artificial Intelligence' },
      { value: 'Quantum Computing' },
      { value: 'Machine Learning' },
      { value: 'Deep Learning' },
      { value: 'Natural Language Processing' },
      { value: 'Computer Vision' },
      { value: 'Blockchain' },
      { value: 'Cybersecurity' },
      { value: 'Cloud Computing' },
      { value: 'Data Science' }
    ]
  };
</script>

Multi-Select with Checkboxes

Add checkboxes together with multi-select to render a checkbox against each item. Checked items remain visible in the dropdown so users can add or remove selections without retyping.

<sl-auto-complete-hds multi-select checkboxes id="checkbox-example" label="Technologies" placeholder="Type to search..."></sl-auto-complete-hds>

<script type="module">
  document.getElementById('checkbox-example').data = {
    categories: [],
    data: [
      { value: 'Artificial Intelligence' },
      { value: 'Quantum Computing' },
      { value: 'Machine Learning' },
      { value: 'Deep Learning' },
      { value: 'Natural Language Processing' },
      { value: 'Computer Vision' },
      { value: 'Blockchain' },
      { value: 'Cybersecurity' },
      { value: 'Cloud Computing' },
      { value: 'Data Science' }
    ]
  };
</script>

Tag Truncation

When tag labels are long, use tag-max-length to cap the display length (default 30) and truncate to control the truncation style — middle (default) or end. Hovering or focusing a truncated tag shows the full text in a tooltip.

<div style="display: flex; flex-direction: column; gap: 20px;">
  <sl-auto-complete-hds multi-select id="truncate-middle" label="Middle truncation (default, 30 chars)" truncate="middle" placeholder="Type to select tags"></sl-auto-complete-hds>
  <sl-auto-complete-hds multi-select id="truncate-end" label="End truncation (20 chars)" truncate="end" tag-max-length="20" placeholder="Type to select tags"></sl-auto-complete-hds>
</div>

<script type="module">
  const longData = {
    categories: [],
    data: [
      { value: 'Short Tag' },
      { value: 'Quantum Computing' },
      { value: 'Artificial Intelligence Machine Learning Deep Neural Networks and Natural Language Processing' },
      { value: 'Blockchain Distributed Ledger Technology Smart Contracts and Decentralized Finance Applications' }
    ]
  };

  document.getElementById('truncate-middle').data = longData;
  document.getElementById('truncate-end').data = longData;
</script>

Control the maximum height of the dropdown with the --max-dropdown-height CSS custom property. The default is 200px.

<div style="display: flex; flex-flow: column; gap: 15px">
  <sl-auto-complete-hds style="--max-dropdown-height: 150px" id="height-150" label="Max height 150px" placeholder="Type to filter..."></sl-auto-complete-hds>
  <sl-auto-complete-hds style="--max-dropdown-height: 350px" id="height-350" label="Max height 350px" placeholder="Type to filter..."></sl-auto-complete-hds>
</div>

<script type="module">
  const sharedData = {
    categories: [],
    data: [
      { value: 'Artificial Intelligence' }, { value: 'Machine Learning' },
      { value: 'Deep Learning' }, { value: 'Natural Language Processing' },
      { value: 'Computer Vision' }, { value: 'Blockchain' },
      { value: 'Quantum Computing' }, { value: 'Bioinformatics' },
      { value: 'Cybersecurity' }, { value: 'Cloud Computing' },
      { value: 'Edge Computing' }, { value: 'Internet of Things' },
      { value: 'Data Science' }, { value: 'Robotics' }
    ]
  };

  document.getElementById('height-150').data = sharedData;
  document.getElementById('height-350').data = sharedData;
</script>

Input Minimum Width

In multi-select mode the text input sits on the same row as the selected tags. Use --auto-complete-input-min-width to control how much horizontal space is always reserved for the input. The default is 56px, which keeps the cursor visible without pushing too many tags off the row. This value must be in px — other units (%, em, rem) are not supported.

Use --auto-complete-min-width to control the minimum width of the entire component. The default is 255px, which prevents the prefix icon and input from wrapping onto separate lines when the component is placed in a narrow container.

<div style="display: flex; flex-flow: column; gap: 15px">
  <sl-auto-complete-hds multi-select id="input-min-w-default" label="Default (56 px)" placeholder="Type to filter..."></sl-auto-complete-hds>
  <sl-auto-complete-hds multi-select id="input-min-w-wide" label="Wide input (160 px)" placeholder="Type to filter..." style="--auto-complete-input-min-width: 160px"></sl-auto-complete-hds>
</div>

<script type="module">
  const sharedData = {
    categories: [],
    data: [
      { value: 'Artificial Intelligence' }, { value: 'Machine Learning' },
      { value: 'Deep Learning' }, { value: 'Natural Language Processing' },
      { value: 'Computer Vision' }, { value: 'Blockchain' },
      { value: 'Quantum Computing' }, { value: 'Cybersecurity' }
    ]
  };

  document.getElementById('input-min-w-default').data = sharedData;
  document.getElementById('input-min-w-wide').data = sharedData;

  // Pre-select a few items so the tag row is visible immediately
  const preSelected1 = [
    { value: 'Artificial Intelligence' },
    { value: 'Machine Learning' },
    { value: 'Deep Learning' },
    { value: 'Blockchain' }
  ];
  const preSelected2 = [
    { value: 'Artificial Intelligence' },
    { value: 'Machine Learning' },
    { value: 'Deep Learning' }
  ];
  document.getElementById('input-min-w-default').selectedItems = [...preSelected1];
  document.getElementById('input-min-w-wide').selectedItems = [...preSelected2];
</script>

Custom Item Rendering

Use the renderItem property to replace the default option layout with any Lit html template. The function receives the item and a context object with:

searchString — the current raw search string
category — the category the item belongs to (if any)
highlight(text) — wraps matched characters in <b> tags

<sl-auto-complete-hds multi-select id="custom-render" label="Search clients & accounts" placeholder="Try: John or Premium" style="--max-dropdown-height: 300px; --dropdown-padding: 12px"></sl-auto-complete-hds>

<script type="module">
  import { html } from 'https://cdn.jsdelivr.net/npm/lit@3/+esm';

  const el = document.getElementById('custom-render');

  el.data = {
    categories: [{ id: 2, category: 'Accounts' },
      { id: 1, category: 'Clients' }
    ],
    data: [
      { value: "Maldonado's Trust with Ind Trustee - 2410919", accountName: "Maldonado's Trust with Ind Trustee",accountNumber: '2410919', accountProduct: 'Global Investment Services',            accountBalance: '' },
      { value: "Armand Maldonado's Trust with Ind Trustee - 24109194",categoryId: 2, accountName: "Armand Maldonado's Trust with Ind Trustee",accountNumber: '24109194', accountProduct: 'Global Investment Services',            accountBalance: '' },
      { value: 'Abbot Watson And Vincent Calhoun - 24055496',          categoryId: 2, accountName: 'Abbot Watson And Vincent Calhoun',          accountNumber: '24055496', accountProduct: 'Global Investment Services',            accountBalance: '' },
      { value: 'Alan Donaldson - 24122882',                           categoryId: 2, accountName: 'Alan Donaldson',                           accountNumber: '24122882', accountProduct: 'Global Investment Services',            accountBalance: '' },
      { value: 'Donaldson - 2412288', accountName: 'Donaldson',                           accountNumber: '2412288', accountProduct: 'Global Investment Services',            accountBalance: '' },
      { value: 'Alan May',                                            categoryId: 1, initials: 'AM', email: '' },
      { value: "Alan May's Superfund with Corp Trustee - 24182611",   categoryId: 2, accountName: "Alan May's Superfund with Corp Trustee",   accountNumber: '24182611', accountProduct: 'Premium - HUB24 Invest - CHOICE Menu', accountBalance: '' },
      { value: 'Alden',                                               categoryId: 1, initials: 'A',  email: '' },
      { value: "Alden Mccarty's Trust with Corp Trustee - 24099902",  categoryId: 2, accountName: "Alden Mccarty's Trust with Corp Trustee",  accountNumber: '24099902', accountProduct: 'Global Investment Services',            accountBalance: '' }
    ]
  };

  el.renderItem = (item, { highlight, category }) => {
    if (category?.id === 1) {
      return html`
        <div style="display:flex;align-items:center;gap:10px;width:100%">
          <sl-avatar initials=${item.initials} label=${item.value} style="--size:32px"></sl-avatar>
          <div style="min-width:0">
            <div style="font-weight:500">${highlight(item.value)}</div>
            <div style="font-size:12px;color:#6b7280">${highlight(item.email)}</div>
          </div>
        </div>
      `;
    }
    if (category?.id === 2) {
      return html`
        <div style="display:flex;flex-direction:column;gap:4px;width:100%;padding:4px 0">
          <div style="display:flex;justify-content:space-between;align-items:baseline">
            <span style="font-weight:500;font-size:14px">${highlight(item.accountName)}</span>
            <span style="font-size:12px;color:#6b7280">#${item.accountNumber}</span>
          </div>
          <div style="display:flex;justify-content:space-between;align-items:baseline">
            <span style="font-size:12px;color:#6b7280">${item.accountProduct}</span>
            <span style="font-size:13px;font-weight:500">${item.accountBalance}</span>
          </div>
        </div>
      `;
    }
    return html`<div>${highlight(item.value)}</div>`;
  };
</script>

Performance with Large Datasets

For large lists, enable virtual-scroll to use virtualised rendering — only visible items are rendered in the DOM regardless of dataset size. This example loads 20,000 items across 4 categories.

<sl-auto-complete-hds virtual-scroll multi-select id="perf-example" label="Search 20,000 items" placeholder="Type to filter..." style="--max-dropdown-height: 300px"></sl-auto-complete-hds>

<script type="module">
  const categories = [
    { id: 1, category: 'Technology' },
    { id: 2, category: 'Finance' },
    { id: 3, category: 'Healthcare' },
    { id: 4, category: 'Education' }
  ];

  const data = [];
  for (let i = 1; i <= 20000; i++) {
    data.push({ value: `Item ${String(i).padStart(5, '0')}`, categoryId: ((i - 1) % 4) + 1 });
  }

  document.getElementById('perf-example').data = { categories, data };
</script>

Backend Filtering

Use backend-filter when results should be fetched from a server on each keystroke rather than filtered locally. The component emits a search-string event — your handler fetches the results and sets them back via the data property. A built-in loading spinner is shown while results are pending.

Key behaviours in backend-filter mode:

The dropdown only opens when the user types — it never auto-opens on focus.
After selecting an item the dropdown closes. In multi-select the input is cleared ready for a new query; in single-select the input shows the selected value (re-focusing re-opens the dropdown for a new search).
The search-string event is debounced by 500 ms.
Clearing or blurring the input resets the dropdown and discards stale results.

Single Select

<sl-auto-complete-hds backend-filter id="be-single" label="Search" placeholder="Type to search..."></sl-auto-complete-hds>

<script type="module">
  const allData = [
    { value: 'Artificial Intelligence' }, { value: 'Quantum Computing' },
    { value: 'Machine Learning' },        { value: 'Deep Learning' },
    { value: 'Natural Language Processing' }, { value: 'Computer Vision' },
    { value: 'Blockchain' },              { value: 'Cybersecurity' },
    { value: 'Cloud Computing' },         { value: 'Edge Computing' },
    { value: 'Internet of Things' },      { value: 'Data Science' },
    { value: 'Robotics' },                { value: 'Bioinformatics' },
    { value: 'Quantum Cryptography' }
  ];

  document.getElementById('be-single').addEventListener('search-string', (e) => {
    const q = (e.detail ?? '').trim().toLowerCase();
    const filtered = q ? allData.filter(item => item.value.toLowerCase().includes(q)) : [];
    e.target.data = { categories: [], data: filtered };
  });
</script>

Multi-Select

<sl-auto-complete-hds multi-select backend-filter id="be-multi" label="Search" placeholder="Type to search..."></sl-auto-complete-hds>

<script type="module">
  const allData = [
    { value: 'Artificial Intelligence' }, { value: 'Quantum Computing' },
    { value: 'Machine Learning' },        { value: 'Deep Learning' },
    { value: 'Natural Language Processing' }, { value: 'Computer Vision' },
    { value: 'Blockchain' },              { value: 'Cybersecurity' },
    { value: 'Cloud Computing' },         { value: 'Edge Computing' },
    { value: 'Internet of Things' },      { value: 'Data Science' },
    { value: 'Robotics' },                { value: 'Bioinformatics' },
    { value: 'Quantum Cryptography' }
  ];

  document.getElementById('be-multi').addEventListener('search-string', (e) => {
    const q = (e.detail ?? '').trim().toLowerCase();
    const filtered = q ? allData.filter(item => item.value.toLowerCase().includes(q)) : [];
    e.target.data = { categories: [], data: filtered };
  });
</script>

Multi-Select with Checkboxes

<sl-auto-complete-hds multi-select checkboxes backend-filter id="be-checkboxes" label="Search" placeholder="Type to search..."></sl-auto-complete-hds>

<script type="module">
  const allData = [
    { value: 'Artificial Intelligence' }, { value: 'Quantum Computing' },
    { value: 'Machine Learning' },        { value: 'Deep Learning' },
    { value: 'Natural Language Processing' }, { value: 'Computer Vision' },
    { value: 'Blockchain' },              { value: 'Cybersecurity' },
    { value: 'Cloud Computing' },         { value: 'Edge Computing' },
    { value: 'Internet of Things' },      { value: 'Data Science' },
    { value: 'Robotics' },                { value: 'Bioinformatics' },
    { value: 'Quantum Cryptography' }
  ];

  document.getElementById('be-checkboxes').addEventListener('search-string', (e) => {
    const q = (e.detail ?? '').trim().toLowerCase();
    const filtered = q ? allData.filter(item => item.value.toLowerCase().includes(q)) : [];
    e.target.data = { categories: [], data: filtered };
  });
</script>

States

Disabled

Use disabled to prevent all interaction. Pre-set selectedItems still render as tags.

<sl-auto-complete-hds multi-select disabled label="Disabled" id="state-disabled"></sl-auto-complete-hds>

<script type="module">
  const el = document.getElementById('state-disabled');
  el.data = {
    data: [
      { value: 'Artificial Intelligence' }, { value: 'Quantum Computing' },
      { value: 'Machine Learning' }, { value: 'Computer Vision' }
    ]
  };
  el.selectedItems = [
    { value: 'Natural Language Processing' },
    { value: 'Computer Vision' }
  ];
</script>

Readonly

Use readonly to show the current selection without allowing changes. Tags are displayed but their remove buttons are hidden.

<sl-auto-complete-hds multi-select readonly label="Readonly" id="state-readonly"></sl-auto-complete-hds>

<script type="module">
  const el = document.getElementById('state-readonly');
  el.data = {
    data: [
      { value: 'Artificial Intelligence' }, { value: 'Quantum Computing' },
      { value: 'Machine Learning' }, { value: 'Computer Vision' }
    ]
  };
  el.selectedItems = [
    { value: 'Natural Language Processing' },
    { value: 'Computer Vision' }
  ];
</script>

Required

Add required to enable native form validation. The field is invalid when no item is selected. In multi-select mode, having at least one tag satisfies the requirement. Use value-missing-message to customise the validation message.

  <sl-auto-complete-hds required multi-select label="Technologies (required)" id="state-required"></sl-auto-complete-hds>
  <sl-auto-complete-hds required multi-select label="Custom message" value-missing-message="Please select at least one technology." id="state-required-custom"></sl-auto-complete-hds>

<script type="module">
  const requiredData = {
    data: [
      { value: 'Artificial Intelligence' }, { value: 'Quantum Computing' },
      { value: 'Machine Learning' }, { value: 'Deep Learning' },
      { value: 'Computer Vision' }, { value: 'Robotics' }
    ]
  };
  document.getElementById('state-required').data = requiredData;
  document.getElementById('state-required-custom').data = requiredData;
</script>

Events

The component emits three events:

Event	When	Detail
`sl-change`	Selection changes (item added or removed)	`{ value: DataItem[] }` — full current selection
`update-item`	An item is added or removed	`{ added: DataItem \| null, removed: DataItem \| null }`
`search-string`	Input value changes (debounced in `backend-filter` mode)	`string` — current input value

<sl-auto-complete-hds multi-select id="events-example" label="Technologies" placeholder="Type to select..."></sl-auto-complete-hds>
<div id="events-log" style="margin-top:10px;padding:10px;background:#f3f4f6;border-radius:6px;font-size:12px;font-family:monospace;min-height:40px;max-height:120px;overflow:auto"></div>

<script type="module">
  const el = document.getElementById('events-example');
  const log = document.getElementById('events-log');

  el.data = {
    categories: [],
    data: [
      { value: 'Artificial Intelligence' }, { value: 'Quantum Computing' },
      { value: 'Machine Learning' },        { value: 'Deep Learning' },
      { value: 'Computer Vision' },         { value: 'Robotics' }
    ]
  };

  function appendLog(msg) {
    log.innerHTML += `<div>${msg}</div>`;
    log.scrollTop = log.scrollHeight;
  }

  el.addEventListener('sl-change', (e) => {
    appendLog(`sl-change → [${e.detail.value.map(i => i.value).join(', ')}]`);
  });

  el.addEventListener('update-item', (e) => {
    const { added, removed } = e.detail;
    if (added) appendLog(`update-item → added: ${added.value}`);
    if (removed) appendLog(`update-item → removed: ${removed.value}`);
  });
</script>

Reactivity

Setting Selected Items Programmatically

Set selectedItems at any time to update the selection from outside the component — useful for pre-filling from saved state or syncing with other form controls.

Set 1 item

Set 2 items

Set many items

Clear

<div style="display:flex;gap:8px;flex-wrap:wrap;margin-bottom:12px">
  <sl-button id="btn-set-one">Set 1 item</sl-button>
  <sl-button id="btn-set-two">Set 2 items</sl-button>
  <sl-button id="btn-set-many">Set many items</sl-button>
  <sl-button id="btn-clear">Clear</sl-button>
</div>
<sl-auto-complete-hds multi-select label="Technologies" id="reactive-example"></sl-auto-complete-hds>

<script type="module">
  const el = document.getElementById('reactive-example');

  el.data = {
    data: [
      { value: 'Artificial Intelligence' }, { value: 'Quantum Computing' },
      { value: 'Machine Learning' },        { value: 'Deep Learning' },
      { value: 'Natural Language Processing' }, { value: 'Computer Vision' },
      { value: 'Robotics' },                { value: 'Internet of Things' },
      { value: 'Big Data' },                { value: 'Cloud Computing' },
      { value: 'Blockchain' },              { value: 'Cybersecurity' },
      { value: 'Data Science' },            { value: 'Virtual Reality' },
      { value: 'Augmented Reality' },       { value: 'Edge Computing' },
      { value: '5G Technology' },           { value: 'Autonomous Vehicles' },
      { value: 'DevOps' },                  { value: 'Microservices' },
      { value: 'Neural Networks' },         { value: 'Large Language Models' },
      { value: 'Federated Learning' },      { value: 'Explainable AI' },
      { value: 'AI Ethics' }
    ]
  };

  document.getElementById('btn-set-one').addEventListener('click', () => {
    el.selectedItems = [{ value: 'Quantum Computing' }];
  });

  document.getElementById('btn-set-two').addEventListener('click', () => {
    el.selectedItems = [
      { value: 'Quantum Computing' },
      { value: 'Artificial Intelligence' }
    ];
  });

  document.getElementById('btn-set-many').addEventListener('click', () => {
    el.selectedItems = [
      { value: 'Artificial Intelligence' }, { value: 'Quantum Computing' },
      { value: 'Machine Learning' },        { value: 'Deep Learning' },
      { value: 'Natural Language Processing' }, { value: 'Computer Vision' },
      { value: 'Robotics' },                { value: 'Internet of Things' },
      { value: 'Big Data' },                { value: 'Cloud Computing' },
      { value: 'Blockchain' },              { value: 'Cybersecurity' },
      { value: 'Data Science' },            { value: 'Virtual Reality' },
      { value: 'Augmented Reality' }
    ];
  });

  document.getElementById('btn-clear').addEventListener('click', () => {
    el.selectedItems = [];
  });
</script>

Keyboard Interaction

The component supports keyboard navigation when the dropdown is open. Use ↓ / ↑ or Tab / Shift+Tab to move between items, Enter to select, and Escape to close.

[component-metadata:sl-auto-complete-hds]

Slots

Name	Description
`prefix`	The prefix slot. Defaults to a magnifying glass icon.
`suffix`	The suffix slot.
`label`	The input’s label. Alternatively, you can use the `label` attribute.
`help-text`	Text that describes how to use the autocomplete. Alternatively, you can use the `help-text` attribute.

Learn more about using slots.

Properties

Name	Description	Type	Default
`data`	The data to display in the auto-complete dropdown.	`AutoCompleteData`	`{ categories: [], data: [] }`
`label`	The autocomplete’s label. If you need to display HTML, use the `label` slot instead.	`string`	`''`
`labelSuffix` `label-suffix`	The autocomplete’s label suffix.	`string`	`''`
`labelInline` `label-inline`	Set to true to display the label inline with the input.	`boolean`	`false`
`valueMissingMessage` `value-missing-message`	The message to display when the field is required but empty.	`string`	`'This field is required'`
`helpText` `help-text`	The help text of the autocomplete element. If you need to display HTML, use the `help-text` slot instead.	`string`	`''`
`multiSelect` `multi-select`	Set to true to enable multi-select.	`boolean`	`false`
`checkboxes`	Enables checkbox mode in the dropdown.	`boolean`	`false`
`size`	The size of the input element.	`'small' \| 'medium' \| 'large'`	`'medium'`
`disabled`	Set to true to disable the autocomplete.	`boolean`	`false`
`readonly`	Set to true to make the autocomplete read-only.	`boolean`	`false`
`required`	Set to true to make the input required. Note that in multi-select mode, the required state is only enforced when no items are selected.	`boolean`	`false`
`backendFilter` `backend-filter`	Set to true to enable backend filtering.	`boolean`	`false`
`minSearchChars` `min-search-chars`	Minimum typed characters before showing dropdown.	`number`	`0`
`maxResults` `max-results`	Maximum number of results to display in the dropdown. If maxResults is 0, all results are shown.	`number`	`0`
`virtualScroll` `virtual-scroll`	Set to true to enable virtual scrolling for large lists. Uses @lit-labs/virtualizer.	`boolean`	`false`
`noResultsText` `no-results-text`	The text to display when there are no results.	`string`	`'No results match your search.'`
`placeholder`	Placeholder text for the input field.	`string`	`'Type to search…'`
`autofocus`	Set to true to autofocus the input field.	`boolean`	`false`
`truncationStyle` `truncate`	Controls how text is truncated in tags. Options are ‘middle’ or ‘end’	`'middle' \| 'end'`	`'middle'`
`tagMaxLength` `tag-max-length`	Maximum number of characters shown in a tag before truncation kicks in.	`number`	`30`
`renderItem`	Custom render function for dropdown items. Receives the item and a context object with `searchString` and `category`.	`RenderItemFn \| undefined`	-
`updateComplete`	A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name	Description	Event Detail
`sl-change`	Emitted when the selection changes. Detail contains `{ value: DataItem[] }` — always the full current selection.	`CustomEvent`
`update-item`	Emitted when an item is added or removed from the selected items.	-
`search-string`	Emitted when the input value changes, allowing for backend filtering or other actions based on the search string.	-

Learn more about events.

Custom Properties

Name	Description	Default
`--max-dropdown-height`	Maximum height of the dropdown. Default: 200px.
`--dropdown-padding`	Padding inside the dropdown. Default: 4px. Use 12px for roomy spacing.
`--auto-complete-min-width`	Minimum width of the entire component. Default: 255px.
`--auto-complete-input-min-width`	Minimum width of the input field when tags are present. Must be a `px` value. Default: 56px. Adjust based on your design and expected tag lengths.
`--avatar-border-radius-rounded`	Border radius for rounded avatars.

Learn more about customizing CSS custom properties.

Parts

Name	Description
`base`	The component’s base wrapper.
`dropdown`	The scrollable dropdown container.
`listbox`	The dropdown list element (ul).
`option`	A single dropdown option item (li).
`option-label`	The label inside a dropdown option.
`category-header`	A category group header (li).
`category-divider`	The divider between category groups (li).
`no-results`	The no-results message container.
`prefix-icon`	The default magnifying glass prefix icon.
`auto-complete-hds--form-control-label`	The sl-input form control label (exported via exportparts).
`auto-complete-hds--clear-button`	The sl-input clear button (exported via exportparts).

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

<sl-checkbox>
<sl-divider>
<sl-empty-state>
<sl-icon>
<sl-icon-button>
<sl-input>
<sl-popup>
<sl-tag>
<sl-tooltip>

Examples

Label

Label Suffix

Minimum Search Characters

Clear Icon Slot

Help Text

Sizes

Placeholder

Prefix

Suffix

Max Results

Searching

No Results

Multi-Select

Multi-Select with Checkboxes

Tag Truncation

Dropdown Height

Input Minimum Width

Custom Item Rendering

Performance with Large Datasets

Backend Filtering

Single Select

Multi-Select

Multi-Select with Checkboxes

States

Disabled

Readonly

Required

Events

Reactivity

Setting Selected Items Programmatically

Keyboard Interaction

Slots

Properties

Events

Custom Properties

Parts

Dependencies