search module

Package:

@microsoft/teams-js

Note

This namespace is in Beta and provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Allows your application to interact with the host M365 application's search box. By integrating your application with the host's search box, users can search your app using the same search box they use elsewhere in Teams, Outlook, or Office.

This functionality is in Beta.

Interfaces

SearchQuery

This interface contains information pertaining to the contents of the host M365 application's search box

Type Aliases

SearchQueryHandler

This type will store the SearchQuery and allow other logic to be made inside the handler.

Functions

closeSearch()	Clear the host M365 application's search box
isSupported()	Checks if search capability is supported by the host
registerHandlers(SearchQueryHandler, SearchQueryHandler, SearchQueryHandler)	Allows the caller to register for various events fired by the host search experience. Calling this function indicates that your application intends to plug into the host's search box and handle search events, when the user is actively using your page/tab. The host may visually update its search box, e.g. with the name or icon of your application. Your application should not re-render inside of these callbacks, there may be a large number of onChangeHandler calls if the user is typing rapidly in the search box. Example search.registerHandlers( query => { console.log('Update your application to handle the search experience being closed. Last query: ${query.searchTerm}'); }, query => { console.log(`Update your application to handle an executed search result: ${query.searchTerm}`); }, query => { console.log(`Update your application with the changed search query: ${query.searchTerm}`); }, );
unregisterHandlers()	Allows the caller to unregister for all events fired by the host search experience. Calling this function will cause your app to stop appearing in the set of search scopes in the hosts

Function Details

closeSearch()

Note

This API is in Beta and provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Clear the host M365 application's search box

function closeSearch(): Promise<void>

Returns

Promise<void>

isSupported()

Note

This API is in Beta and provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Checks if search capability is supported by the host

function isSupported(): boolean

Returns

boolean

boolean to represent whether the search capability is supported

registerHandlers(SearchQueryHandler, SearchQueryHandler, SearchQueryHandler)

Note

This API is in Beta and provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Allows the caller to register for various events fired by the host search experience. Calling this function indicates that your application intends to plug into the host's search box and handle search events, when the user is actively using your page/tab.

The host may visually update its search box, e.g. with the name or icon of your application.

Your application should not re-render inside of these callbacks, there may be a large number of onChangeHandler calls if the user is typing rapidly in the search box.

Example

search.registerHandlers(
   query => {
     console.log('Update your application to handle the search experience being closed. Last query: ${query.searchTerm}');
   },
   query => {
     console.log(`Update your application to handle an executed search result: ${query.searchTerm}`);
   },
   query => {
     console.log(`Update your application with the changed search query: ${query.searchTerm}`);
   },
  );

function registerHandlers(onClosedHandler: SearchQueryHandler, onExecuteHandler: SearchQueryHandler, onChangeHandler?: SearchQueryHandler)

Parameters

onClosedHandler

SearchQueryHandler

This handler will be called when the user exits or cancels their search. Should be used to return your application to its most recent, non-search state. The value of searchTerm will be whatever the last query was before ending search.

onExecuteHandler

SearchQueryHandler

The handler will be called when the user executes their search (by pressing Enter for example). Should be used to display the full list of search results. The value of searchTerm is the complete query the user entered in the search box.

onChangeHandler

SearchQueryHandler

This optional handler will be called when the user first starts using the host's search box and as the user types their query. Can be used to put your application into a word-wheeling state or to display suggestions as the user is typing.

This handler will be called with an empty searchTerm when search is beginning, and subsequently, with the current contents of the search box.

unregisterHandlers()

Note

This API is in Beta and provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Allows the caller to unregister for all events fired by the host search experience. Calling this function will cause your app to stop appearing in the set of search scopes in the hosts

function unregisterHandlers()