Components v2 Home Header Menu Search User Login Footer Test

byu-search

Because there are as many ways to perform a search as there are webpages, byu-search has several built-in search options, with hooks to provide your own implementation with Javascript.

Styling

Note: None of the styling search examples will actually run a search. The actual search action will be covered later.

You can either provide an input element for byu-search to style, or you can let byu-search provide one for you. It is preferred that you provide an input element, as this enables graceful degredation if something goes wrong while downloading and executing the Javascript which powers byu-search.

In many cases, your input will need to be nested in another element, such as a form:

By default, byu-search will search for the first child input and style it. If you need to customize which element will be styled by byu-search, you can set the search-input-selector attribute to a CSS selector which will match your input:

Beware, though, because this is a two-edged sword! If your search-input-selector value doesn't match an input, the search bar won't render properly! We will, however, emit a helpful error message into the developer console to warn you about what's happening:

Handling Searches

When the user clicks the search button or hits the enter key while focused on the search element, byu-search will take some action to actually perform the search. You can use a pre-defined action to run the search, or you can take a custom action using Javascript.

Pre-built Actions

Out of the box, byu-search supports different pre-defined actions to perform the search. You can use the action attribute to specify which action to take, and the action-target attribute to modify that action.

You can:

action="submit-form"

A common way to handle searches is to simply use a form. It's straightforward, easy, and is built right in to HTML! Using action="submit-form", you can enclose your search element in a form.

action="click"

action="click" will simulate a click on an element. The element MUST be a child of byu-search.

By default, byu-search will find the first button, input type="submit", or input type="button", and call click() on it:

If you need to customize the element that is clicked, you can pass a CSS selector as the actionTarget attribute.

Caveats/Limitations

For security reasons, browsers do not allow clicks to be simulated on <a> tags. So, if you use actionTarget to select an <a> tag, a search may not do anything (depending on the browser implementation). If you want to send the user to a URL, use a form with action="submit-form" or use action="navigate".

action="navigate"

If you just want to redirect the user to a certain page and embed the search query in the URL, you can use action="navigate". If you use this action, you MUST specify an actionTarget value which contains a URL pattern to which the user will be sent. byu-search will look for the string '${search}' in the URL pattern. For example, to perform a Google search, you would set actionTarget to "https://google.com/search?q=${search}".

Custom Actions

If none of the built in actions fit your needs, byu-search fires a byu-search event that you can use to perform some custom action. You can listen for this event in two ways: via an onbyusearch attribute or by adding an event handler using Javascript.

The event that is fired will have a type of 'byu-search' and will have a details object containing search, which contains the user-entered search text.

Why event.detail.search?

This matches the CustomEvent specification.

onbyusearch attribute

You can specify a Javascript function to call using onbyusearch. Unlike a normal HTML event handler, like onclick, you cannot specify arbitrary Javascript. The value MUST be a globally-available function name.

Within the callback function, this will be bound to the byu-search element. The callback function will be passed a single parameter, the byu-search event.

Event Listener

Instead of using onbyusearch, you can also use Javascript to set up listeners for the search event, using addEventListener().

You can also use addEventListener and onbyusearch to prevent the predefined actions from firing by calling preventDefault() on the event. This is useful, for example, if you want to restrict searching to a list of predefined terms.

In this example, if you search for most terms, the button will be clicked and you'll see an alert saying "Searched using a click." If you enter "Utah Football Rocks", you'll see an alert saying "No, it doesn't," and the default click action will not be performed.

oninput Event

It is possible to be notified when the search input value has changed using the standard input event. This can be useful for external scripts such as AJAX suggestions.