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 matching document field's value would be displayed.

// 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

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

set the title of the component to be shown in the UI.

loader

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

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.
• setAfter (after: object, options?: Options) => void

can be used to set the after property, which is useful while implementing pagination when the type of the component is term. The after key is a a property of aggregationData.

• 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.

<SearchBox
	renderError={error => (
		<div>
			Something went wrong!
			<br />
			Error details
			<br />
			{JSON.stringify(error)}
		</div>
	)}
/>

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-icon key in the innerClass prop.

    <SearchBox
        ...
        enableRecentSearches
        innerClass={{
            'recent-search-icon': '...',
        }}
        recentSearchesIcon={<RecentIcon />}
    />

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-icon key in the innerClass prop.

    <SearchBox
        ...
        enablePopularSuggestions
        innerClass={{
            'popular-search-icon': '...'
        }}
        popularSearchesIcon={<PopularIcon />}
    />

focusShortcuts

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

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

addonBefore

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.

<SearchBox
    showIcon={false}
    addonBefore={
        <img
            src="https://img.icons8.com/cute-clipart/64/000000/search.png"
            height="30px"
        />
    }
    id="search-component"
    ...
/>

addonAfter

The HTML markup displayed after (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.

<SearchBox
    showIcon={false}
    addonAfter={
        <img
            src="https://img.icons8.com/cute-clipart/64/000000/search.png"
            height="30px"
        />
    }
    id="search-component"
    ...
/>

expandSuggestionsContainer

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

<SearchBox
    expandSuggestionsContainer={false}
    addonBefore={
          <img ... />
        }
    addonAfter={
          <img ... />
        }
    id="search-component"
    ...
/>

enterButton

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.

    <SearchBox            
        id="search-component"
        enterButton={true}
    />

renderEnterButton

renders a custom jsx markup for the enter button. Use in conjunction with enterButton prop set to true.

    <SearchBox
        id="search-component"
        enterButton
        renderEnterButton={clickHandler => (
            <div
                style={{
                    height: '100%',
                    display: 'flex',
                    alignItems: 'stretch',
                }}
            >
                <button style={{ border: '1px solid #c3c3c3' }} onClick={clickHandler}>
                    🔍 Search
                </button>
            </div>
        )}
    />

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
• recent-search-icon
• popular-search-icon
• enter-button

className

CSS class to be injected on the component container.

style

CSS styles to be applied to the SearchBox component.

Controlled behavior

defaultValue

set the initial search query text on mount.

value

sets the current value of the component. It sets the search query text (on mount and on update). Use this prop in conjunction with the onChange prop.

onChange

is a callback function which accepts component's current value as a parameter. It is called when you are using the value prop and the component's value changes.

Callbacks for change events

onValueChange

is a callback function 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.

onValueSelected

A function callback which executes on selecting a value from result set

onError

gets triggered in case of an error while fetching results

onResults

can be used to listen for the suggestions changes

onQueryChange

is a callback function 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.

onBlur

is a callback handler for input blur event

onKeyPress

is a callback handler for keypress event

onKeyUp

is a callback handler for keyup event

onFocus

is a callback handler for input focus event

onKeyDown

is a callback handler for keydown event

onAggregationData

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

To customize the query execution

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

<SearchBox id="search-component" dataField={['original_title', 'original_title.search']} />

• transformRequest (requestOptions: Object) => Promise<Object> 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.

<SearchBox
	id="search-component"
	dataField={['original_title', 'original_title.search']}
	transformRequest={request =>
		Promise.resolve({
			...request,
			credentials: include,
		})
	}
/>

• transformResponse (response: any) => Promise<any> 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:

<SearchBox
	id="search-component"
	dataField={['original_title', 'original_title.search']}
	transformResponse={async 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,
			},
		};
	}}
/>

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: (component: SearchComponent) => Object 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.

<SearchBox
    id="search-component"
    dataField={["original_title", "original_title.search"]}
    defaultQuery={() => ({
        "timeout": "1s"
    })}
/>

• customQuery: (component: SearchComponent) => Object 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.

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

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 Function 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:

<SearchBox
	id="search-component"
	dataField={['original_title', 'original_title.search']}
	beforeValueChange={function(value) {
		// called before the value is set
		// returns a promise
		return new Promise((resolve, reject) => {
			// update state or component props
			resolve();
			// or reject()
		});
	}}
/>

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.

• 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.

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