Types
Standard
A search can display a set of results
Category
A search can display results from remote content ordered by categories
Local Search
A search can look for results inside a static local source.
$('.ui.search')
.search({
source: content
})
;
var content = [
{ title: 'Andorra' },
{ title: 'United Arab Emirates' },
{ title: 'Afghanistan' },
{ title: 'Antigua' },
{ title: 'Anguilla' },
{ title: 'Albania' },
{ title: 'Armenia' },
{ title: 'Netherlands Antilles' },
{ title: 'Angola' },
{ title: 'Argentina' },
{ title: 'American Samoa' },
{ title: 'Austria' },
{ title: 'Australia' },
{ title: 'Aruba' },
{ title: 'Aland Islands' },
{ title: 'Azerbaijan' },
{ title: 'Bosnia' },
{ title: 'Barbados' },
{ title: 'Bangladesh' },
{ title: 'Belgium' },
{ title: 'Burkina Faso' },
{ title: 'Bulgaria' },
{ title: 'Bahrain' },
{ title: 'Burundi' }
// etc
];
Local Category Search
New in 2.3
A search can look for category results inside a static local source.
$('.ui.search')
.search({
type: 'category',
source: categoryContent
})
;
var categoryContent = [
{ category: 'South America', title: 'Brazil' },
{ category: 'South America', title: 'Peru' },
{ category: 'North America', title: 'Canada' },
{ category: 'Asia', title: 'South Korea' },
{ category: 'Asia', title: 'Japan' },
{ category: 'Asia', title: 'China' },
{ category: 'Europe', title: 'Denmark' },
{ category: 'Europe', title: 'England' },
{ category: 'Europe', title: 'France' },
{ category: 'Europe', title: 'Germany' },
{ category: 'Africa', title: 'Ethiopia' },
{ category: 'Africa', title: 'Nigeria' },
{ category: 'Africa', title: 'Zimbabwe' },
];
States
Loading
A search can show a loading indicator
Variations
Disabled
New in 2.3.1
A search can show it is currently unable to be interacted with
Fluid
A search can have its results take up the width of its container
Aligned
A search can have its results aligned to its left or right container edge
Initializing
Automatic Routing
By default search will automatically route to the named API endpoint 'search'
// initializes with default endpoint /search/{query}
$('.ui.search')
.search({
type: 'category'
})
;
Named URL
You can specify custom API settings to adjust the url, callback settings, or specify a different API action.
$('.ui.search')
.search({
// change search endpoint to a custom endpoint by manipulating apiSettings
apiSettings: {
url: 'custom-search/?q={query}'
},
type: 'category'
})
;
Local Object
Local search results allow you to search across specified properties of a javacript object literal looking for matching values
You can set which fields are searchable using the searchFields setting. Local object search can only display standard search results (not categories).
// searches across any array/object of searchable objects
var
content = [
{
title: 'Horse',
description: 'An Animal',
},
{
title: 'Cow',
description: 'Another Animal',
}
]
;
$('.ui.search')
.search({
source : content,
searchFields : [
'title'
],
fullTextSearch: false
})
;
Server Responses
Standard
{
"results": [
{
"title": "Result Title",
"url": "/optional/url/on/click",
"image": "optional-image.jpg",
"price": "Optional Price",
"description": "Optional Description"
},
{
"title": "Result Title",
"description": "Result Description"
}
],
// optional action below results
"action": {
"url": '/path/to/results',
"text": "View all 202 results"
}
}
Category
{
"results": {
"category1": {
"name": "Category 1",
"results": [
{
"title": "Result Title",
"url": "/optional/url/on/click",
"image": "optional-image.jpg",
"price": "Optional Price",
"description": "Optional Description"
},
{
"title": "Result Title",
"url": "/optional/url/on/click",
"image": "optional-image.jpg",
"price": "Optional Price",
"description": "Optional Description"
}
]
},
"category2": {
"name": "Category 2",
"results": [
{
"title": "Result Title",
"url": "/optional/url/on/click",
"image": "optional-image.jpg",
"price": "Optional Price",
"description": "Optional Description"
}
]
}
},
// optional action below results
"action": {
"url": '/path/to/results',
"text": "View all 202 results"
}
}
Retreiving Results
Unique IDs
If no id property is included on a result, a key will automatically be generated when your results are returned for each result.
IDs are generated using the position in the results, for example the first element will receive the id 1, and the first category result will receive the id a1.
An id or search result title can then be used with get result(value) to return the result object.
// get result from current query results with the title cat
$('.ui.search')
.search('get result', 'cat')
;
// get first result from first category with category search
$('.ui.search')
.search('get result', 'a1')
;
// get first result from standard search
$('.ui.search')
.search('get result', '1')
;
Behaviors
All the following behaviors can be called using the syntax:
$('.your.element')
.search('behavior name', argumentOne, argumentTwo)
;
| Behavior | Description |
|---|---|
| query (callback) | Search for value currently set in search input |
| display message(text, type) | Displays message in search results with text, using template matching type |
| cancel query | Cancels current remote search query |
| search local(query) | Search local object for specified query and display results |
| has minimum characters | Whether has minimum characters |
| search remote(query, callback) | Search remote endpoint for specified query and display results |
| search object(query, object, searchFields) | Search object for specified query and return results |
| cancel query | Cancels current remote search request |
| is focused | Whether search is currently focused |
| is visible | Whether search results are visible |
| is empty | Whether search results are empty |
| get value | Returns current search value |
| get result(value) | Returns JSON object matching searched title or id (see above) |
| set value(value) | Sets search input to value |
| read cache(query) | Reads cached results for query |
| clear cache(query) | Clears value from cache, if no parameter passed clears all cache |
| write cache(query) | Writes cached results for query |
| add results(html) | Adds HTML to results and displays |
| show results(callback) | Shows results container |
| hide results(callback) | Hides results container |
| generate results(response) | Generates results using parser specified by settings.template |
| destroy | Removes all events |
Examples
Using Different Response Fields
Search expects a very specific API response, however you can easily modify the mapping of server response to displayed field using the fields parameter.
$('.ui.search')
.search({
apiSettings: {
url: '//api.github.com/search/repositories?q={query}'
},
fields: {
results : 'items',
title : 'name',
url : 'html_url'
},
minCharacters : 3
})
;
Using API Settings
API provides a callback onResponse that can be used to restructure third party APIs to match the expected server response for search.
You can also use mockResponseAsync to use a custom backend for fullfilling searches.
$('.ui.search')
.search({
type : 'category',
minCharacters : 3,
apiSettings : {
onResponse: function(githubResponse) {
var
response = {
results : {}
}
;
// translate GitHub API response to work with search
$.each(githubResponse.items, function(index, item) {
var
language = item.language || 'Unknown',
maxResults = 8
;
if(index >= maxResults) {
return false;
}
// create new language category
if(response.results[language] === undefined) {
response.results[language] = {
name : language,
results : []
};
}
// add result to category
response.results[language].results.push({
title : item.name,
description : item.description,
url : item.html_url
});
});
return response;
},
url: '//api.github.com/search/repositories?q={query}'
}
})
;
Search
Behavior
| Default | Description | |
|---|---|---|
| apiSettings |
{
action: 'search'
}
|
Settings for API call. |
| minCharacters | 1 | Minimum characters to query for results |
| searchOnFocus | true | Whether search should show results on focus (must also match min character length) |
| transition | fade | Named transition to use when animating menu in and out. Fade and slide down are available without including ui transitions |
| duration | 300 | Duration of animation events |
| maxResults | 7 | Maximum results to display when using local and simple search, maximum category count for category search |
| cache | true | Caches results locally to avoid requerying server |
| source | false | Specify a Javascript object which will be searched locally |
| selectFirstResult | false | Whether the search should automatically select the first search result after searching |
| showNoResults | false | Whether a "no results" message should be shown if no results are found. (These messages can be modified using the template object specified below) |
| fullTextSearch | 'exact' | Specifying to "true" will use a fuzzy full text search, setting to "exact" will force the exact search to be matched somewhere in the string, setting to false will only match to start of string. (This setting was previously called searchFullText.) |
| fields |
fields: {
categories : 'results', // array of categories (category view)
categoryName : 'name', // name of category (category view)
categoryResults : 'results', // array of results (category view)
description : 'description', // result description
image : 'image', // result image
price : 'price', // result price
results : 'results', // array of results (standard)
title : 'title', // result title
action : 'action', // "view more" object name
actionText : 'text', // "view more" text
actionURL : 'url' // "view more" url
}
|
List mapping display content to JSON property, either with API or source. |
| searchFields |
[
'title',
'description'
]
|
Specify object properties inside local source object which will be searched |
| hideDelay | 0 | Delay before hiding results after search blur |
| searchDelay | 100 | Delay before querying results on inputchange |
| easing | easeOutExpo | Easing equation when using fallback Javascript animation |
Callbacks
| Context | Description | |
|---|---|---|
| onSelect(result, response) | module | Callback on element selection by user. The first parameter includes the filtered response results for that element. The function should return false to prevent default action (closing search results and selecting value). |
| onResultsAdd(html) | module | Callback after processing element template to add HTML to results. Function should return false to prevent default actions. |
| onSearchQuery(query) | module | Callback on search query |
| onResults(response) | module | Callback on server response |
| onResultsOpen | results element | Callback when results are opened |
| onResultsClose | results element | Callback when results are closed |
Templates
These templates are used to generate the HTML structures for search results
| Functions | |
|---|---|
| templates |
$.fn.search.settings.templates : {
escape: function(string) {
// returns escaped string for injected results
},
message: function(message, type) {
// returns html for message with given message and type
},
category: function(response) {
// returns results html for category results
},
standard: function(response) {
// returns results html for standard results
}
}
|
Module
These settings are native to all modules, and define how the component ties content to DOM attributes, and debugging settings for the module.
| Default | Description | |
|---|---|---|
| name | Search | Name used in log statements |
| namespace | search | Event namespace. Makes sure module teardown does not effect other events attached to an element. |
| regExp |
regExp: {
escape : /[\-\[\]\/\{\}\(\)\*\+\?\.\\\^\$\|]/g,
beginsWith : '(?:\s|^)'
}
|
Regular expressions used for matching |
| selector |
selector : {
prompt : '.prompt',
searchButton : '.search.button',
results : '.results',
category : '.category',
result : '.result'
}
|
Selectors used to find parts of a module |
| metadata |
metadata: {
cache : 'cache',
results : 'results'
}
|
HTML5 metadata attributes used internally |
| className |
className: {
active : 'active',
empty : 'empty',
focus : 'focus',
loading : 'loading',
pressed : 'down'
}
|
Class names used to determine element state |
| silent | False | Silences all console output including error messages, regardless of other debug settings. |
| debug | false | Debug output to console |
| performance | true | Show console.table output with performance metrics |
| verbose | false | Debug output includes all internal behaviors |
| errors |
error : {
source : 'Cannot search. No source used, and Semantic API module was not included',
noResults : 'Your search returned no results',
logging : 'Error in debug logging, exiting.',
noTemplate : 'A valid template name was not specified.',
serverError : 'There was an issue with querying the server.',
maxResults : 'Results must be an array to use maxResults setting',
method : 'The method you called is not defined.'
},
|
|