enablePredictiveSuggestions

Defaults to `false`. When set to `true`, it predicts the next relevant words from a field's value based on the search query typed by the user. When set to `false` (default), the entire field's value would be displayed. This may not be desirable for long-form fields (where average words per field value is greater than 4 and may not fit in a single line).

// pass this prop as true in searchComponent to enable predictive suggestions
:enablePredictiveSuggestions="true",

maxPredictedWords

Defaults to 2. This property allows configuring the maximum number of relevant words that are predicted. Valid values are between [1, 5].

applyStopwords

When set to true, it would not predict a suggestion which starts or ends with a stopword. You can find the list of stopwords used by Appbase at here.

• stopwords Array[String] It allows you to define a list of custom stopwords. You can also set it through Index settings in the control plane.

showDistinctSuggestions

Show 1 suggestion per document. If set to false multiple suggestions may show up for the same document as searched value might appear in multiple fields of the same document, this is true only if you have configured multiple fields in dataField prop. Defaults to true.

Example if you have showDistinctSuggestions is set to false and have following configurations

// Your document:
{
    "name": "Warn",
    "address": "Washington"
}
// Component:
<SearchBox dataField={['name', 'address']} />
// Search Query:
"wa"

Then there will be 2 suggestions from the same document as we have the search term present in both the fields specified in dataField.

Warn
Washington

urlField

It is the dataField whose value contains a URL. This is a convenience prop that allows returning the URL value in the suggestion's response.

To customize the SearchBox UI

• title String|JSX set the title of the component to be shown in the UI.

• loader String|JSX Display an optional loader while fetching the options

placeholder

set placeholder text to be shown in the component's input field. Defaults to "Search".

showIcon

whether to display a search or custom icon in the input box. Defaults to true.

iconPosition

sets the position of the search icon. Can be set to either left or right. Defaults to right.

icon

set a custom search icon instead of the default 🔍

showClear

show a clear text X icon. Defaults to false.

clearIcon

sets custom clear icon for the search input box

autosuggest

set whether the autosuggest functionality should be enabled or disabled. Defaults to true.

strictSelection

defaults to false. When set to true, the component will only set its value and fire the query if the value was selected from the suggestion. Otherwise the value will be cleared on selection. This is only relevant with autosuggest.

defaultSuggestions

preset search suggestions to be shown on focus when the SearchBox does not have any search query text set. Accepts an array of objects each having a label and value property. The label can contain either String or an HTML element. For an example

<SearchBox
    defaultSuggestions={[
        {
            label: 'Songwriting',
            value: 'Songwriting'
        },
        {
            label: 'Musicians',
            value: 'Musicians'
        }
    ]}
>

downShiftProps

are the props to be passed to DownShift for typeahead configurations

debounce

delays executing the query by the specified time in ms while the user is typing. Defaults to 0, i.e. no debounce. Useful if you want to save on the Number of requests sent.

showVoiceSearch

Enable voice search for searchbox

• focusShortcuts Array<String | Number> [optional]

A list of keyboard shortcuts that focus the search box. Accepts key names and key codes. Compatible with key combinations separated using '+'. Defaults to ['/'].

Note

1. By default, pressing '/' would focus the search box.
2. The hotkeys-js library needs to be installed manually when using combinations in focusShortcuts prop, eg: 'cmd+b', 'ctrl+q', etc, without which only single key shortcuts would work if passed in the prop, eg: From among ['/', 'b', '#', 'ctrl+r'], only '/', 'b', '#' would work without hotkey-js installation.

autoFocus

[optional] When set to true, search box is auto-focused on page load. Defaults to false.

expandSuggestionsContainer

[optional] When set to false the width of suggestions dropdown container is limited to the width of searchbox input field. Defaults to true.

 <search-box
        expandSuggestionsContainer={false}
        ...
  >
    <img slot="addonBefore" src="..." />
    <img slot="addonAfter" src="..." />
 </search-box>

enterButton

[optional] When set to true, the results would only be updated on press of the button. Defaults to false. You can also provide styles using the enter-button key in the innerClass prop.

<img src="https://i.imgur.com/8ZoA42b.png" style="margin:0 auto;display:block;"/>

 <search-box
    :enterButton="true"        
  >
  // ... other slots
 </search-box>

Customize style

innerClass

SearchBox component supports an innerClass prop to provide styles to the sub-components of SearchBox. These are the supported keys:

• title
• input
• list
• enter-button

className

CSS class to be injected on the component container.

style

CSS styles to be applied to the SearchBox component.

To customize the query execution

headers

set custom headers to be sent with each server request as key/value pairs. For example:

<search-box
	id="search-component"
	:dataField="['original_title', 'original_title.search']"
	:headers="{
		secret: 'searchbase-is-awesome',
	}"
/>

transformRequest

Enables transformation of network request before execution. This function will give you the request object as the param and expect an updated request in return, for execution.
For example, we will add the credentials property in the request using transformRequest.

<template>
	<search-box
		id="search-component"
		:dataField="['original_title', 'original_title.search']"
		:transformRequest="transformRequest"
	/>
</template>
<script>
	export default {
		name: 'App',
		methods: {
			transformRequest(request) {
				return Promise.resolve({
					...request,
					credentials: include,
				});
			},
		},
	};
</script>

transformResponse

Enables transformation of search network response before rendering them. It is an asynchronous function which will accept an Elasticsearch response object as param and is expected to return an updated response as the return value.
For example:

<template>
	<search-box
		id="search-component"
		:dataField="['original_title', 'original_title.search']"
		:transformResponse="transformResponse"
	/>
</template>
<script>
	export default {
		name: 'App',
		methods: {
			async transformResponse(elasticsearchResponse) {
				const ids = elasticsearchResponse.hits.hits.map(item => item._id);
				const extraInformation = await getExtraInformation(ids);
				const hits = elasticsearchResponse.hits.hits.map(item => {
					const extraInformationItem = extraInformation.find(
						otherItem => otherItem._id === item._id,
					);
					return {
						...item,
						...extraInformationItem,
					};
				});

				return {
					...elasticsearchResponse,
					hits: {
						...elasticsearchResponse.hits,
						hits,
					},
				};
			},
		},
	};
</script>

Note

transformResponse function is expected to return data in the following structure.

    {
        // Elasticsearch hits response
        hits: {
            hits: [...],
            total: 100
        },
        // Elasticsearch aggregations response
        aggregations: {

        }
        took: 1
    }

defaultQuery

is a callback function that takes SearchComponent instance as parameter and returns the data query to be applied to the suggestions, as defined in Elasticsearch Query DSL, which doesn't get leaked to other components. In simple words, defaultQuery is used with data-driven components to impact their own data.

For example, set the timeout to 1s for suggestion query.

<template>
	<search-box
		id="search-component"
		:dataField="['original_title', 'original_title.search']"
		:defaultQuery="defaultQuery"
	/>
</template>
<script>
	export default App {
	    name: 'App',
	    methods: {
	        defaultQuery() {
	            return {
	                "timeout": "1s"
	            }
	        }
	    }
	}
</script>

customQuery

takes SearchComponent instance as parameter and returns the query to be applied to the dependent components by react prop, as defined in Elasticsearch Query DSL.

For example, the following example has two components search-component(to render the suggestions) and result-component(to render the results). The result-component depends on the search-component to update the results based on the selected suggestion. The search-component has the customQuery prop defined that will not affect the query for suggestions(that is how customQuery is different from defaultQuery) but it'll affect the query for result-component because of the react dependency on search-component.

<template>
	<search-base
		index="gitxplore-app"
		url="https://@arc-cluster-appbase-demo-6pjy6z.searchbase.io"
		credentials="a03a1cb71321:75b6603d-9456-4a5a-af6b-a487b309eb61"
	>
		<search-box
			id="search-component"
			:dataField="['original_title', 'original_title.search']"
			:customQuery="customQuery"
		/>
		<search-component
			id="result-component"
			dataField="original_title"
			:react="{
                and: ['search-component']
            }"
		/>
	</search-base>
</template>
<script>
	export default App {
	    name: 'App',
	    methods: {
	        customQuery() {
	            return {
	                timeout: '1s',
	                query: {
	                    match_phrase_prefix: {
	                        fieldName: {
	                            query: 'hello world',
	                            max_expansions: 10,
	                        },
	                    },
	                },
	            }
	        }
	    }
	}
</script>

Miscellaneous

getMicInstance

You can pass a callback function to get the instance of SpeechRecognition object, which can be used to override the default configurations for voice search.

beforeValueChange

is a callback function which accepts component's future value as a parameter and returns a promise. It is called every-time before a component's value changes. The promise, if and when resolved, triggers the execution of the component's query and if rejected, kills the query execution. This method can act as a gatekeeper for query execution, since it only executes the query after the provided promise has been resolved. For example:

<template>
	<search-box
		id="search-component"
		:dataField="['original_title', 'original_title.search']"
		:beforeValueChange="beforeValueChange"
	/>
</template>
<script>
	export default App {
	    name: 'App',
	    methods: {
	        beforeValueChange(value) {
	            // called before the value is set
	            // returns a promise
	            return new Promise((resolve, reject) => {
	                // update state or component props
	                resolve();
	                // or reject()
	            });
	        }
	    }
	}
</script>

URLParams

enable creating a URL query String param based on the search query text value. This is useful for sharing URLs with the component state. Defaults to false.

defaultValue

set the initial search query text on mount.

• subscribeTo Array<String>

lets you subscribe to various Searchbox properties to render UI (or to create a side-effect) based on changes to the properties.
These are the properties that can be subscribed to:

• results
• aggregationData
• requestStatus
• error
• value
• query
• micStatus
• dataField
• size
• from
• fuzziness
• includeFields
• excludeFields
• sortBy
• react
• defaultQuery
• customQuery

Events

• change is an event emitted when value of the component changes, which accepts component's current value, searchComponent ref and the e event object as parameters. It is called when you are using the value prop and the component's value changes.

<search-box
	:value="text"
	@change="(value, searchComponent, e) => {
		this.text = value;
		// To fetch suggestions
		searchComponent.triggerDefaultQuery();
		// To update results
		searchComponent.triggerCustomQuery();
	}"
/>

• valueChange is an event which accepts component's current value as a parameter. It is called every-time the component's value changes. This prop is handy in cases where you want to generate a side-effect on value selection. For example: You want to show a pop-up modal with the valid discount coupon code when a user searches for a product in a SearchBox.

• valueSelected An event which gets triggered on selecting a value from suggestions

• error gets triggered in case of an error while fetching suggestions

• results can be used to listen for the suggestions changes

• queryChange

is an event which accepts component's prevQuery and nextQuery as parameters. It is called everytime the component's query changes. This prop is handy in cases where you want to generate a side-effect whenever the component's query would change.

• blur is an event handler for input blur event

• keyPress is an event handler for keypress event

• keyUp is an event handler for keyup event

• focus is an event handler for input focus event

• keyDown is an event handler for keydown event

• aggregationData can be used to listen for the aggregationData property changes

  • data: Array<Object> contains the parsed aggregations
  • raw: Object Response returned by ES composite aggs query in the raw form.
  • rawData: Object An object of raw response as-is from elasticsearch query.
  • afterKey: Object If the Number of composite buckets is too high (or unknown) to be returned in a single response use the afterKey parameter to retrieve the next

Slots

render

You can render suggestions in a custom layout by using the render prop.
It accepts an object with these properties:

• loading: Boolean indicates that the query is still in progress.
• error: Object An object containing the error info.
• suggestions: () => Array<Object> This method can be used to get the parsed suggestions from the results. The suggestion object will have the following shape:

{
    label: string;
    value: string;
    _suggestion_type: string;
    source: object;
}

• results Results

It is an object which contains the following details of suggestions query response. - data: Array<Object> contains the (promoted data + parsed hits)

• raw: Object Response returned by ES query in the raw form.

  • NumberOfResults: Number Total Number of results found
  • time: Number Total time taken by request (in ms)
  • hidden: Number Total Number of hidden results found
  • promoted: Number Total Number of promoted results found
  • promotedData: Array<Object> An array of promoted results obtained from the applied query.
  • customData: Object An object of custom data obtained from the ReactiveSearch API.
  • rawData: Object An object of raw response as-is from elasticsearch query.

• aggregationData Aggregations It is an object which contains the following details of aggregations query response.

  • data: Array<Object> contains the parsed aggregations
  • raw: Object Response returned by ES composite aggs query in the raw form.
  • rawData: Object An object of raw response as-is from elasticsearch query.
  • afterKey: Object If the Number of composite buckets is too high (or unknown) to be returned in a single response use the afterKey parameter to retrieve the next results. This property will only be present for composite aggregations.

• value current search input value i.e the search query being used to obtain suggestions.

• query Object The last query that has been executed to fetch the suggestions

• micStatus MicStatusField Returns the current status of the mic. Can be INACTIVE, ACTIVE or DENIED

• micActive Boolean Returns true if mic is active

• micInactive Boolean Returns true if mic is inactive

• micDenied Boolean Returns true if it doesn't have access to the mic

• micInstance Object Returns the current mic instance. Can be used to set mic language and other properties of mic

• id String as defined in props

• react Object react as defined in props

• queryFormat String as defined in props

• dataField String | Array<String | DataField> as defined in props

• categoryField String as defined in props

• categoryValue String represents the current value of the selected category

• nestedField String as defined in props

• from Number represents the current state of the from value. This property is useful to implement pagination.

• size Number represents the current state of the size of results to be returned by query

• sortBy String current state of the sortBy value

• aggregationField String as defined in props

• includeFields Array<String> represents the current value of includeFields property

• excludeFields represents the current value of excludeFields property

• fuzziness String|Number represents the current value of fuzziness property

• searchOperators Boolean as defined in props

• highlight Boolean as defined in props

• highlightField String|Array<String> as defined in props

• customHighlight Object as defined in props

• enableSynonyms Boolean as defined in props

• queryString String as defined in props

• enablePopularSuggestions Boolean as defined in props

• showDistinctSuggestions Boolean as defined in props

• defaultQuery represents the current value of defaultQuery property

• customQuery represents the current value of customQuery property

• requestStatus represents the current state of the request, can have values as INACTIVE, PENDING or ERROR.

• appbaseConfig Object as defined in props

• queryId String to get the query id returned by appbase.io search to track the analytics

• subscribeToStateChanges function can be used to subscribe to the changes for the properties. Read more at here.

• unsubscribeToStateChanges function can be used to unsubscribe to the changes for the properties. Read more at here.

• recordClick function enables recording click analytics of a search request. Please check the usage at here.

• recordConversions function enables recording conversions of a search request. Please check the usage at here.

Note: All of the methods accept options as the second parameter which has the following shape:

{
    triggerDefaultQuery?: Boolean, // defaults to `true`
    triggerCustomQuery?: Boolean, // defaults to `false`
    stateChanges?: Boolean // defaults to `true`
};

triggerDefaultQuery

true executes the query for a particular component

triggerCustomQuery

true executes the query for the dependent components (dependencies defined in the react property)

stateChanges

true invokes the subscribed functions to subscribeToStateChanges method, i.e trigger the re-render after making changes

• handleMicClick (micOptions: Object, options: Options): Promise<any> can be used to handle the custom voice search implementation
• triggerDefaultQuery (options): Promise<any> can be used to trigger the customQuery programmatically
• triggerCustomQuery (options): Promise<any> can be used to trigger the defaultQuery programmatically
• setDataField ( dataField: String | Array<String | DataField>, options?: Options ) => void
• setValue ( value: any, options?: Options ) => void can be used to set the value property
• setCategoryValue (categoryValue: string, options?: Options) => void

can be used to set the categoryValue property.

• setSize ( size: Number, options?: Options ) => void can be used to set the size property
• setFrom ( from: Number, options?: Options ) => void can be used to set the from property. Useful to implement pagination.
• setFuzziness ( fuzziness: String|Number, options?: Options ) => void can be used to set the fuzziness property.
• setIncludeFields ( includeFields: Array<String>, options?: Options ) => void can be used to set the includeFields property.
• setExcludeFields ( excludeFields: Array<String>, options?: Options ) => void can be used to set the excludeFields property.
• setSortBy ( sortBy: String, options?: Options ) => void can be used to set the sortBy property.
• setReact ( react: Object, options?: Options ) => void can be used to set the react property.
• setDefaultQuery ( defaultQuery: function, options?: Options ) => void can be used to set the defaultQuery property.
• setCustomQuery ( customQuery: function, options?: Options ) => void can be used to set the customQuery property.

renderError

can be used to render an error message in case of any error.

<search-box slot="renderError" slot-scope="error">
    <div>
        Something went wrong!<br/>Error details<br/>{JSON.Stringify(error)}
    </div>
</search-box>

renderNoSuggestion

can be used to render a message in case of no list items.

renderMic

can be used to render the custom mic option

recentSearchesIcon

You can use a custom icon in place of the default icon for the recent search items that are shown when enableRecentSearches prop is set to true. You can also provide styles using the recent-search-icon key in the innerClass prop.

    <search-box
        ...
        :enableRecentSearches="true"
        :innerClass="{
            'recent-search-icon': '...',
        }"
    >
        <recent-icon slot="recentSearchesIcon" />
    </search-box>

popularSearchesIcon

You can use a custom icon in place of the default icon for the popular searches that are shown when enablePopularSuggestions prop is set to true. You can also provide styles using the popular-search-icon key in the innerClass prop.

<search-box
    ...
    :enablePopularSuggestions="true"
    :innerClass="{
        'popular-search-icon': '...'
    }"
>
    <popular-icon slot="popularSearchesIcon" />
</search-box>

• addonBefore slot-scope [optional] The HTML markup displayed before (on the left side of) the searchbox input field. Users can use it to render additional actions/ markup, eg: a custom search icon hiding the default.

<search-box
      ...
      :enablePopularSuggestions="true"
      :innerClass="{
         'popular-search-icon': '...'
      }"
>
      <img 
        slot="addonBefore"
        src="https://img.icons8.com/cute-clipart/64/000000/search.png"
        height="30px"
      />
</search-box>

• addonAfter slot-scope [optional] The HTML markup displayed before (on the right side of) the searchbox input field. Users can use it to render additional actions/ markup, eg: a custom search icon hiding the default.

<search-box
      ...
      :enablePopularSuggestions="true"
      :innerClass="{
         'popular-search-icon': '...'
      }"
>
      <img 
        slot="addonAfter"
        src="https://img.icons8.com/cute-clipart/64/000000/search.png"
        height="30px"
      />
</search-box>

• renderEnterButton slot-scope [optional] The custom HTML markup displayed for enterButton. Use in conjunction with enterButton prop set to true.

<search-box
      ...
      :enterButton="true"
>
    <div
        slot="renderEnterButton"
        slot-scope="onClick"
        :style="{ height: '100%', display: 'flex', alignItems: 'stretch' }"
    >
        <button
            :style="{ border: '1px solid #c3c3c3', cursor: 'pointer' }"
            v-on:click="onClick"
        >
            🔍 Search
        </button>
    </div>
</search-box>