Search

In-Memory Filter

Pass filter and slot all <q2-option> children upfront. The component case-insensitively matches each option's display and innerText against the query and toggles hidden automatically.

<q2-search label="Find a fruit" filter clearable>
    <q2-option value="apple" display="Apple"></q2-option>
    <q2-option value="banana" display="Banana"></q2-option>
    <q2-option value="cherry" display="Cherry"></q2-option>
    <q2-option value="date" display="Date"></q2-option>
    <q2-option value="elderberry" display="Elderberry"></q2-option>
</q2-search>

Async Fetch

Listen to tctInput, fetch results, swap the slotted options, and toggle loading while the request is in flight. Debounce the fetch to avoid hammering the server on every keystroke.

<q2-search id="customers" label="Find a customer" placeholder="Type to search"></q2-search>
<script>
    const CUSTOMERS = [
        { id: 'c1', name: 'Alice Johnson' },
        { id: 'c2', name: 'Bob Smith' },
        { id: 'c3', name: 'Carol White' },
        { id: 'c4', name: 'David Brown' },
        { id: 'c5', name: 'Eve Martinez' },
    ];
    const el = document.getElementById('customers');
    let timer;
    el.addEventListener('tctInput', e => {
        const q = e.detail.query.trim().toLowerCase();
        clearTimeout(timer);
        el.innerHTML = '';
        if (!q) { el.loading = false; return; }
        el.loading = true;
        timer = setTimeout(() => {
            const results = CUSTOMERS.filter(c => c.name.toLowerCase().includes(q));
            el.innerHTML = results.map(r =>
                `<q2-option value="${r.id}" display="${r.name}"></q2-option>`).join('');
            el.loading = false;
        }, 400);
    });
</script>

Multi-Select

Add multiple to allow selecting more than one option. Combine with filter for in-memory filtering, or with tctInput for async fetch.

<q2-search label="Find fruits" multiple filter>
    <q2-option value="apple" display="Apple"></q2-option>
    <q2-option value="banana" display="Banana"></q2-option>
    <q2-option value="cherry" display="Cherry"></q2-option>
    <q2-option value="date" display="Date"></q2-option>
    <q2-option value="elderberry" display="Elderberry"></q2-option>
</q2-search>

Multi-Select with Selected Toggle

Add show-selected-toggle to render a header inside the popover that lets the user switch between search results and only their selected options.

<q2-search label="Find fruits" multiple filter show-selected-toggle>
    <q2-option value="apple" display="Apple"></q2-option>
    <q2-option value="banana" display="Banana"></q2-option>
    <q2-option value="cherry" display="Cherry"></q2-option>
    <q2-option value="date" display="Date"></q2-option>
    <q2-option value="elderberry" display="Elderberry"></q2-option>
</q2-search>

Grouped Options

Wrap related <q2-option> children in <q2-optgroup> to render them as a labeled group. Useful for categorized results such as recents vs. suggestions.

<q2-search label="Find a transfer" filter>
    <q2-optgroup label="Recent">
        <q2-option value="r1" display="Checking → Savings"></q2-option>
        <q2-option value="r2" display="Checking → Roth IRA"></q2-option>
    </q2-optgroup>
    <q2-optgroup label="Saved">
        <q2-option value="s1" display="Rent payment"></q2-option>
        <q2-option value="s2" display="Loan payment"></q2-option>
    </q2-optgroup>
</q2-search>

Recents and Secondary Actions

Pre-slot <q2-option> children to show recent searches before the user types. Use the popover-top slot for persistent actions like "Clear recents", and popover-bottom for footer actions like "View all results".

<q2-search id="recents-search" label="Search">
    <div slot="popover-top" style="padding: 8px 12px;">
        <q2-btn id="clear-recents-btn" intent="workflow-secondary" style="width: 100%;">Clear recents</q2-btn>
    </div>
    <q2-option value="r1" display="Recent search 1"></q2-option>
    <q2-option value="r2" display="Recent search 2"></q2-option>
</q2-search>
<script>
    document.getElementById('clear-recents-btn').addEventListener('click', () => {
        const search = document.getElementById('recents-search');
        search.querySelectorAll('q2-option').forEach(o => o.remove());
    });
</script>

Input-Only Mode

When no options, empty slot, popover-top, or popover-bottom content is provided, the popover is suppressed and q2-search behaves as a styled search input. tctInput still fires on every keystroke.

<q2-search label="Free-text search" placeholder="Type anything"></q2-search>

Reserve Loading Height

Set --tct-search-loading-popover-height to reserve space while loading is true, preventing a layout jump when results arrive. In the example below the spinner appears immediately when you start typing.

<q2-search
    id="reserve-height-search"
    label="Find a customer"
    placeholder="Type to search"
    style="--tct-search-loading-popover-height: 220px;"
></q2-search>
<script>
    const NAMES = ['Alice Johnson', 'Bob Smith', 'Carol White', 'David Brown', 'Eve Martinez'];
    const el = document.getElementById('reserve-height-search');
    let timer;
    el.addEventListener('tctInput', e => {
        const q = e.detail.query.trim().toLowerCase();
        clearTimeout(timer);
        el.innerHTML = '';
        if (!q) { el.loading = false; return; }
        el.loading = true;
        timer = setTimeout(() => {
            const results = NAMES.filter(n => n.toLowerCase().includes(q));
            el.innerHTML = results.map((n, i) =>
                `<q2-option value="n${i}" display="${n}"></q2-option>`).join('');
            el.loading = false;
        }, 800);
    });
</script>

Popover Alignment

Use popover-alignment to anchor the popover to the left or right edge of the input rather than stretching it to match the input width. Requires --tct-popover-width (in px) on the host; without it the component logs a warning and falls back to input-width. When the viewport is narrower than the defined width, the component automatically falls back to block (input-width) mode.

left anchors the popover's left edge to the input's left edge — useful when the input sits near the right edge of the layout. right anchors the popover's right edge to the input's right edge — useful when the input sits near the left edge.

<div style="display: flex; gap: 16px; align-items: flex-start;">
    <q2-search
        label="Left-aligned"
        popover-alignment="left"
        style="--tct-popover-width: 320px; width: 160px;"
        filter
    >
        <q2-option value="apple" display="Apple"></q2-option>
        <q2-option value="banana" display="Banana"></q2-option>
        <q2-option value="cherry" display="Cherry"></q2-option>
        <q2-option value="date" display="Date"></q2-option>
        <q2-option value="elderberry" display="Elderberry"></q2-option>
    </q2-search>

    <q2-search
        label="Right-aligned"
        popover-alignment="right"
        style="--tct-popover-width: 320px; width: 160px; margin-left: 50px;"
        filter
    >
        <q2-option value="apple" display="Apple"></q2-option>
        <q2-option value="banana" display="Banana"></q2-option>
        <q2-option value="cherry" display="Cherry"></q2-option>
        <q2-option value="date" display="Date"></q2-option>
        <q2-option value="elderberry" display="Elderberry"></q2-option>
    </q2-search>
</div>

When to Use Q2-Search

Primary Use Cases

Large or Dynamic Option Sets Use q2-search when the full option list is too large to display upfront, or when options are fetched from a server in response to a query (e.g., customer lookup, account search).

Search-First Workflows Ideal when the user already knows what they're looking for and would rather type than browse:

• Customer or account search
• Product or payee lookup
• Address or location autocomplete
• Tag or category assignment

When NOT to Use Q2-Search

Small, Static Lists If the option set has fewer than ~10 items and the full list can be shown upfront, prefer q2-select — browsing is faster than searching for short lists.

Binary or Near-Binary Choices Avoid for yes/no or two-to-four option fields; use radio buttons or q2-select instead.

Q2-Search vs Q2-Select (with searchable)

Both components emit tctInput and can drive async fetch. The difference is the interaction model:

| | q2-search | q2-select + searchable | |---|---|---| | Default state | Empty input, no list visible | Full option list visible immediately | | User intent | Knows what they want — types to find it | May browse before deciding | | Option set size | Large or unbounded (e.g., all customers) | Bounded — full list is meaningful to show | | Multi-select | Yes (multiple prop) | Yes (multiple prop) | | Async fetch | Yes | Yes (via tctInput) | | Best for | Lookup, autocomplete, free-text search | Category, status, role — especially when browsing helps |

Choose q2-search when the full option list is too large or too dynamic to show upfront, or when the workflow is explicitly search-first (e.g., find a customer by name, look up a payee).

Choose q2-select + searchable when the list is bounded enough to browse, but a search shortcut improves usability for power users (e.g., a list of 20–50 accounts where a user might want to type "sav" to jump to savings accounts rather than scroll).

Input-Only Mode

When no options are slotted and no popover-top, popover-bottom, or empty slot content is provided, q2-search suppresses the popover entirely and behaves as a styled search input. tctInput still fires on every keystroke — use this mode to submit a free-text query to a search results page rather than selecting from a dropdown.

Multi-Select

Add multiple to allow the user to select more than one option. When blurred, the input shows the first selection's display text with a +N badge for the remaining count. When focused, the badge shows the total count alongside the in-progress query.

Add show-selected-toggle to render a header inside the popover that lets the user switch between viewing search results and only their selected options.

User Experience Guidelines

• Always provide a meaningful label — do not rely solely on placeholder.
• Use placeholder to hint at the expected input format (e.g., "Name or account number").
• Reserve loading for async fetch flows — show it while results are in flight and clear it when options are ready.
• Use the popover-top slot for persistent actions like "Clear recent searches" or "Search all results".
• Use the popover-bottom slot for footer actions like "View all results →".
• Use the empty slot (or noResultsMessage prop) to give users constructive feedback when no results match.