Search Form | Kickstand UI

In this guide you will see some of the more common ways to use Kickstand UI to add search to your site as well as some of the features simplify the process.

One fo the most common use-cases for search is the "site search" that is usually found in the header of the page. Kickstand's inline form makes this very simple.

<ks-form inline>
    <ks-form-field label="Search" type="search"></ks-form-field>
    <ks-button type="submit">
        <ks-icon icon="search" label="search"></ks-icon>
    </ks-button>
</ks-form>

ACCESSIBILITY NOTE

The label property is used on the icon in the search button. This populates the aria-label property which is visible to screen readers and other assistive technologies.

# Styling Your Form

Now, if this form is going in header of your page, you might want it to be a little more compact. Let's hide the label, make it more compact, remove the background.

<ks-form class="p-none b-none bg-transparent" inline>
    <ks-form-field label="Search" type="search" size="sm" hide-label></ks-form-field>
    <ks-button type="submit" size="sm">
        <ks-icon icon="search" label="search"></ks-icon>
    </ks-button>
</ks-form>

ACCESSIBILITY NOTE

The hide-label property was added to the form field to hide the label, but it is still visible to screen readers and other assistive technologies.

# Inline Button

To reduce the amount of buttons that stand out in the UI, many designers choose to display the button within the input field. Rather than absolutely position the button over the input field and wrestle with spacing to get everything lined up just right, you can style the form so it has the appearance of being set within the input. To accomplish this we will do 3 things:

Remove the shadow, background, and border of the input
Add the inner shadow, and border to the form
Update the button to display as clear

<ks-form class="p-none b-none bg-transparent b-xxxs shadow-inner" inline>
    <ks-form-field label="Search" type="search" size="sm" input-class="bg-transparent shadow-none b-none" hide-label></ks-form-field>
    <ks-button type="submit" size="sm" display="clear">
        <ks-icon icon="search" label="search"></ks-icon>
    </ks-button>
</ks-form>

# Getting Search Value

The <ks-form> element emits a submitted event when it is submitted by pressing enter or clicking the submit button. The event will emit with the form data and validation information in the event.detail property.

# Form Setup

First, let's add a form and listen for the submitted event:

<ks-form id="search" inline>
    ...
</ks-form>
<script>
    $('#search').on('submitted', (event) => {
        ...
    });
</script>

NOTE

This guide uses the Kickstand UI DOM utilities to help keep the code clean and easy to read.

# Display Results

Next, for display purposes, let's display the search results in a modal when it gets submitted.

<ks-modal id="search_modal" modal-title="You just submitted...">
    <pre id="search_data" class="bg-light-light"></pre>
</ks-modal>

When the form gets submitted, let's set the search form content in the modal and show the modal.

$('#search').on('submitted', (event) => {
    let formData = event.detail;
    $('#search_data').innerText = JSON.stringify(formData, null, 2);
    $('#search_modal').show();
});

# Final Result

See the Pen Kickstand UI Getting Search Input Value by break-stuff (@break-stuff) on CodePen.

# Filtering Data

Above we are only displaying the value, but now that we have it, we can do things like send it to an API to perform searches on the server. In the next few examples we will be filtering an array of values.

# Filtering an Array

In this example we will take the following list of names and filter them based on the search form value when the form is submitted:

const names = [
    'Michael Scott',
    'Jim Halpert',
    'Pam Halpert',
    'Dwight Schrute',
    'Jan Levinson',
    'Angela Martin',
    'Ryan Howard'
];

We will use the following function to filter the list of names:

function getFilteredNames(search) {
    return !search
        ? names 
        : names.filter((name) => name.includes(search));
}

Finally, we will be displaying the results in a table and will be updating the UI using the following markup and function:

<table class="table">
    <thead>
        <tr>
            <th>Names</th>
        </tr>
    </thead>
    <tbody id="search_results">
    </tbody>
</table>

<script>
    function setResults(id, results) {
        $(`#${id}`).innerHTML = results.map((result) => `<tr><td>${result}</td></tr>`).join();
    }
</script>

Now we will replace our previous logic that displayed the form data in a modal with the logic to filter and display our list.

$('#search').on('submitted', (event) => {
    let searchValue = event.detail.formData.search;
    let names = getFilteredNames(searchValue);
    setResults('search_results', names);
});

# Filter Result

See the Pen Kickstand UI - Filtering Data by break-stuff (@break-stuff) on CodePen.

# Auto-Submitting Search

There may be times where you want to have the results filter as the user types in the input field. Rather than use a search form we can do the following:

use a search input without a form or submit button
listen for the updated event (which will be emitted each time the user types)
execute our getFilteredNames and setResults functions we created above to update our UI

See the Pen Kickstand UI - Auto-Submitting Search by break-stuff (@break-stuff) on CodePen.

# Debounce

If you are filtering a list locally like we are here, executing the filter on every key stroke is probably fine. However, if you are pulling the results from a server, you probably don't want to make request to the server every time the user types. To help with this you can use the debounce property to wait for the user to stop typing before the code executes. Let's add a debounce method to the form field to delay the filter by half a second (500 milliseconds).

See the Pen Kickstand UI - Sign Up Form by break-stuff (@break-stuff) on CodePen.

# Accessibility

The finish touch is to improve the usability by adding some accessibility love to our search. A nice feature is provide feedback to the user when search results change. If a user can see the screen, they can easily detect changes in the search results, but it's a bit more difficult for users that rely on assistive technologies. To help with that, we need a way to provide that feedback using assistive technologies.

Fortunately, the aria-live (opens new window) attribute is designed to do just that and, fortunately, Kickstand UI's alert component has it built-in.

The first thing we will add is an alert to the page and add the sr-only class to it so it is visually hidden but still available to assistive technologies.

<ks-alert class="sr-only"><span id="search_count"></span> results found</ks-alert>

We have added a span tag with the ID search_count as our placeholder. Let's add some JavaScript to update it when the search results change. Since we have the aria-live attribute on the alert, it will broadcast the change every time we update the results.

function setResults(id, results) {
  $('#search_count').innerText = results.length;
  $(`#${id}`).innerHTML = results
    .map((result) => `<tr><td>${result}</td></tr>`)
    .join("");
}

See the Pen Kickstand UI - Debounce by break-stuff (@break-stuff) on CodePen.

← Password Confirmation Form Star Rating Component →