arcgis-search | References | ArcGIS Maps SDK for JavaScript

ESM

import "@arcgis/map-components/components/arcgis-search";

Inheritance:: ArcgisSearch→PublicLitElement

Since: ArcGIS Maps SDK for JavaScript 4.28

The Search component provides a way to perform search operations on locator service(s), map/feature service feature layer(s), SceneLayers with an associated feature layer, BuildingComponentSublayer with an associated feature layer, GeoJSONLayer, CSVLayer, OGCFeatureLayer, and/or table(s). If using a locator with a geocoding service, the findAddressCandidates operation is used, whereas queries are used on feature layers.

By default, the Search component uses the ArcGIS World Geocoding Service via this URL: https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer. If a global apiKey is present, the Search component uses this URL: https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer. If an apiKey is present on the LocatorSearchSource, then the Search component uses the URL defined by the LocatorSearchSource.url property.

The Search component sets the view on the Search result. The level of detail (LOD) at the center of the view depends on the data source, with higher quality data sources returning extents closer to the feature obtained from the search. To manually define the scale of the view at the Search result, use the zoomScale property of the LocatorSearchSource or LayerSearchSource. Search component results are typically sorted according to their relevance to the search and their relative importance. However, when the scale of the MapView or SceneView is less than or equal to 300,000, the operations support prioritization of candidates based on their distance from a specified point (the center of the view) by passing in the location parameter. Features closest to the input location show up higher in the list of results. This behavior can be changed by using the localSearchDisabled property.

Demo

Properties

Property	Attribute	Type
`activeMenu`	`active-menu`	`ActiveMenu`
`activeSource` readonly		`null \| undefined \| (LayerSearchSource \| LocatorSearchSource)`
`activeSourceIndex`	`active-source-index`	`number`
`allPlaceholder`	`all-placeholder`	`string \| null \| undefined`
`allSources` readonly		`Collection<SupportedSearchSource>`
`autoDestroyDisabled`	`auto-destroy-disabled`	`boolean`
`autoNavigateDisabled`	`auto-navigate-disabled`	`boolean`
`autoSelectDisabled`	`auto-select-disabled`	`boolean`
`defaultSources` readonly		`Collection<SupportedSearchSource>`
`disabled`	`disabled`	`boolean`
`goToOverride`		`GoToOverride \| null \| undefined`
`icon`	`icon`	`IconName`
`includeDefaultSourcesDisabled`	`include-default-sources-disabled`	`boolean \| SourcesHandler`
`label`	`label`	`string \| undefined`
`locationDisabled`	`location-disabled`	`boolean`
`maxResults`	`max-results`	`number`
`maxSuggestions`	`max-suggestions`	`number`
`messageOverrides`		`Record<string, unknown> \| undefined`
`minSuggestCharacters`	`min-suggest-characters`	`number`
`popupDisabled`	`popup-disabled`	`boolean`
`popupTemplate`		`PopupTemplate \| null \| undefined`
`portal`		`Portal \| null \| undefined`
`referenceElement`	`reference-element`	`ArcgisReferenceElement \| string \| undefined`
`resultGraphic` readonly		`Graphic \| null \| undefined`
`resultGraphicDisabled`	`result-graphic-disabled`	`boolean`
`results` readonly		`Array<SearchResults> \| null \| undefined`
`searchAllDisabled`	`search-all-disabled`	`boolean`
`searchTerm`	`search-term`	`string`
`selectedResult` readonly		`SearchResult \| null \| undefined`
`sources`		`Collection<SupportedSearchSource>`
`state` readonly		`SearchViewModelState`
`suggestions` readonly		`Array<SuggestResults> \| null \| undefined`
`suggestionsDisabled`	`suggestions-disabled`	`boolean`
`topLayerDisabled`	`top-layer-disabled`	`boolean`
`view`		`MapViewOrSceneView \| null \| undefined`

activeMenu

Property

Type: ActiveMenu

The current active menu of the Search component.

Attribute: active-menu
Default value: "none"

activeSource

readonly Property

Type: null | undefined | (LayerSearchSource | LocatorSearchSource)

The sources object currently selected. Can be either a LayerSearchSource or a LocatorSearchSource.

Default value: null

activeSourceIndex

Property

Type: number

The selected source's index. This value is -1 when all sources are selected.

Attribute: active-source-index
Default value: 0

allPlaceholder

Property

Type: string | null | undefined

String value used as a hint for input text when searching on multiple sources. See the image below to view the location and style of this text in the context of the component.

Attribute: all-placeholder
Default value: "Find address or place"

allSources

readonly Property

Type: Collection<SupportedSearchSource>

The combined collection of defaultSources and sources. The defaultSources displays first in the Search UI.

autoDestroyDisabled

Property

Type: boolean

If true, the component will not be destroyed automatically when it is disconnected from the document. This is useful when you want to move the component to a different place on the page, or temporarily hide it. If this is set, make sure to call the destroy() method when you are done to prevent memory leaks.

Attribute: auto-destroy-disabled
Default value: false

autoNavigateDisabled

Property

Type: boolean

Indicates whether to automatically navigate to the selected result. If true, will not automatically navigate to the selected result.

Attribute: auto-navigate-disabled
Default value: false

autoSelectDisabled

Property

Type: boolean

By default, the component will automatically select and zoom to the first geocoded result. When true, the findAddressCandidates operation will still geocode the input string, but the top result will not be selected. To work with the geocoded results, you can set up a @arcgisSearchComplete event handler and get the results through the event object.

Attribute: auto-select-disabled
Default value: false

defaultSources

readonly Property

Type: Collection<SupportedSearchSource>

A read-only property that is a Collection of LayerSearchSource and/or LocatorSearchSource. This property may contain ArcGIS Portal locators and any web map or web scene configurable search sources. Web maps or web scenes may contain map/feature service feature layer(s), and/or table(s) as sources.

This property is used to populate the Search UI if the sources property is not set.

disabled

Property

Type: boolean

When true, the component is visually withdrawn and cannot receive user interaction.

Attribute: disabled
Default value: false

goToOverride

Property

Type: GoToOverride | null | undefined

Since: ArcGIS Maps SDK for JavaScript 4.33

This function provides the ability to override either the arcgis-map.goTo() or arcgis-scene.goTo() methods.

Example

component.goToOverride = function(view, goToParams) {
  goToParams.options = {
    duration: updatedDuration
  };
  return view.goTo(goToParams.target, goToParams.options);
};

icon

Property

Type: IconName

Icon which represents the component. Typically used when the component is controlled by another component (e.g. by the Expand component).

See also

Calcite Icons

Attribute: icon
Default value: "search"

includeDefaultSourcesDisabled

Property

Type: boolean | SourcesHandler

When true, will not include defaultSources in the Search UI.

Attribute: include-default-sources-disabled
Default value: false

label

Property

Type: string | undefined

The component's default label.

Attribute: label

locationDisabled

Property

Type: boolean

When true, will disable location services within the component.

Note: The use of this property is only supported on secure origins. To use it, switch your application to a secure origin, such as HTTPS. Note that localhost is considered "potentially secure" and can be used for easy testing in browsers that supports Window.isSecureContext (currently Chrome and Firefox).

Attribute: location-disabled
Default value: false

maxResults

Property

Type: number

The maximum number of results returned by the component if not specified by the source.

Attribute: max-results
Default value: 6

maxSuggestions

Property

Type: number

The maximum number of suggestions returned by the component if not specified by the source.

If working with the default ArcGIS Online Geocoding service, the default remains at 5.

Attribute: max-suggestions
Default value: 6

messageOverrides

Property

Type: Record<string, unknown> | undefined

Replace localized message strings with your own strings.

Note: Individual message keys may change between releases.

minSuggestCharacters

Property

Type: number

The minimum number of characters needed for the search if not specified by the source.

Attribute: min-suggest-characters
Default value: 3

popupDisabled

Property

Type: boolean

By default, the graphic can be clicked to display a Popup. When true, disables displaying the Popup on feature click.

Attribute: popup-disabled
Default value: false

popupTemplate

Property

Type: PopupTemplate | null | undefined

A customized PopupTemplate for the selected feature. Note that any templates defined on allSources take precedence over those defined directly on the template.

portal

Property

Type: Portal | null | undefined

It is possible to search a specified portal instance's locator services Use this property to set this ArcGIS Portal instance to search.

referenceElement

Property

Type: ArcgisReferenceElement | string | undefined

By assigning the id attribute of the Map or Scene component to this property, you can position a child component anywhere in the DOM while still maintaining a connection to the Map or Scene.

See also

Associate components with a Map or Scene component

Attribute: reference-element

resultGraphic

readonly Property

Type: Graphic | null | undefined

The graphic used to highlight the resulting feature or location.

Note: A graphic will be placed in the View's graphics for layer that do not support the highlight method.

resultGraphicDisabled

Property

Type: boolean

If true, the resultGraphic will not display at the location of the selected feature.

Attribute: result-graphic-disabled
Default value: false

results

readonly Property

Type: Array<SearchResults> | null | undefined

An array of objects, each containing a search result from the search.

searchAllDisabled

Property

Type: boolean

By default, the "All" option is displayed by default to search all sources:

When true, no option to search all sources at once is available:

Attribute: search-all-disabled
Default value: false

searchTerm

Property

Type: string

The value of the search box input text string.

Attribute: search-term

selectedResult

readonly Property

Type: SearchResult | null | undefined

The result selected from a search.

See also

sources

Property

Type: Collection<SupportedSearchSource>

The Search component may be used to search features in a map/feature service feature layer(s), SceneLayers with an associated feature layer, BuildingComponentSublayer with an associated feature layer, GeoJSONLayer, CSVLayer or OGCFeatureLayer, or table, or geocode locations with a locator. The sources property defines the sources from which to search for the view specified by the Search component instance. There are two types of sources:

Any combination of these sources may be used together in the same instance of the Search component.

Note: Feature layers created from client-side graphics are not supported.

Examples

// Default sources[] when sources is not specified
[
  {
    url: "https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer",
    singleLineFieldName: "SingleLine",
    outFields: ["Addr_type"],
    name: "ArcGIS World Geocoding Service",
    placeholder: "Adresse",
    resultSymbol: {
       type: "picture-marker",  // autocasts as new PictureMarkerSymbol()
       url: this.basePath + "/images/search/search-symbol-32.png",
       size: 24,
       width: 24,
       height: 24,
       xoffset: 0,
       yoffset: 0
   }
  }
]

// Example of multiple sources[]
let sources = [
{
  url: "https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer",
  singleLineFieldName: "SingleLine",
  name: "Custom Geocoding Service",
  placeholder: "Search Geocoder",
  maxResults: 3,
  maxSuggestions: 6,
  suggestionsEnabled: false,
  minSuggestCharacters: 0
}, {
  layer: new FeatureLayer({
    url: "https://services.arcgis.com/DO4gTjwJVIJ7O9Ca/arcgis/rest/services/GeoForm_Survey_v11_live/FeatureServer/0",
    outFields: ["*"]
  }),
  searchFields: ["Email", "URL"],
  displayField: "Email",
  exactMatch: false,
  outFields: ["*"],
  name: "Point FS",
  placeholder: "example: esri",
  maxResults: 6,
  maxSuggestions: 6,
  suggestionsEnabled: true,
  minSuggestCharacters: 0
},
{
  layer: new FeatureLayer({
    outFields: ["*"]
  });
  placeholder: "esri",
  name: "A FeatureLayer",
  prefix: "",
  suffix: "",
  maxResults: 1,
  maxSuggestions: 6,
  exactMatch: false,
  searchFields: [], // defaults to FeatureLayer.displayField
  displayField: "", // defaults to FeatureLayer.displayField
  minSuggestCharacters: 0
}
];

let sources = [{ ... }, { ... }, { ... }]; // array of sources
searchViewModel.sources = sources;

// Add to source(s)
searchViewModel.sources.push({ ... });  // new source

state

readonly Property

Type: SearchViewModelState

The current state of the component.

Default value: "ready"

suggestions

readonly Property

Type: Array<SuggestResults> | null | undefined

An array of results from the suggest().

This is available if working with a 10.3 or greater geocoding service that has suggest capability loaded or a 10.3 or greater feature layer that supports pagination, i.e. supportsPagination = true.

suggestionsDisabled

Property

Type: boolean

If true, disables suggestions for the component.

This is only available if working with a 10.3 or greater geocoding service that has suggest capability loaded or a 10.3 or greater feature layer that supports pagination, i.e. supportsPagination = true.

Attribute: suggestions-disabled
Default value: false

topLayerDisabled

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.0

When true, disables rendering in the top layer (above overlays and modals). This can be useful for controlling stacking context in complex UI layouts.

Attribute: top-layer-disabled
Default value: false

view

Property

Type: MapViewOrSceneView | null | undefined

The view associated with the component.

Note: The recommended approach is to fully migrate applications to use map and scene components and avoid using MapView and SceneView directly. However, if you are migrating a large application from widgets to components, you might prefer a more gradual transition. To support this use case, the SDK includes this view property which connects a component to a MapView or SceneView. Ultimately, once migration is complete, the arcgis-search component will be associated with a map or scene component rather than using the view property.

Methods

Method	Signature
`clear`	`clear(): void`
`componentOnReady` inherited	`componentOnReady(): Promise<this>`
`destroy`	`destroy(): Promise<void>`
`search`	`search(searchItem?: Graphic \| null \| undefined \| number[] \| Point \| SuggestResult \| string): Promise<null \| undefined \| SearchResponse>`
`setFocus`	`setFocus(): Promise<void>`
`suggest`	`suggest(query?: string): Promise<null \| undefined \| SuggestResponse>`

clear

Method

Signature: clear (): void

Clears the current searchTerm, search results, suggest results, graphic, and graphics layer. It also hides any open menus.

Returns: void

componentOnReady

inherited Method

Signature: componentOnReady (): Promise<this>

Inherited from: PublicLitElement

Creates a promise that resolves once the component is fully loaded.

Returns: Promise<this>

Example

const arcgisSearch = document.querySelector("arcgis-search");
document.body.append(arcgisSearch);
await arcgisSearch.componentOnReady();
console.log("arcgis-search is ready to go!");

destroy

Method

Signature: destroy (): Promise<void>

Permanently destroy the component.

Returns: Promise<void>

search

Method

Signature: search (searchItem?: Graphic | null | undefined | number[] | Point | SuggestResult | string): Promise<null | undefined | SearchResponse>

Depending on the sources specified, search() queries the feature layer(s) and/or performs address matching using any specified locator(s) and returns any applicable results.

Parameters

Parameter	Type	Description	Required
searchItem	`Graphic \| null \| undefined \| number[] \| Point \| SuggestResult \| string`

Returns: Promise<null | undefined | SearchResponse>

setFocus

Method

Signature: setFocus (): Promise<void>

Brings focus to the component's text input.

Returns: Promise<void>

suggest

Method

Signature: suggest (query?: string): Promise<null | undefined | SuggestResponse>

Performs a suggest() request on the active Locator. It also uses the current value of the component or one that is passed in.

Suggestions are available if working with a 10.3 or greater geocoding service that has suggest capability loaded or a 10.3 or greater feature layer that supports pagination, i.e. supportsPagination = true.

Parameters

Parameter	Type	Description	Required
query	`string`

Returns: Promise<null | undefined | SuggestResponse>

Events

Name	Type
`arcgisPropertyChange`	CustomEvent<{ name: "state"; }>
`arcgisReady`	CustomEvent<void>
`arcgisSearchClear`	CustomEvent<SearchViewModelEvents["search-clear"]>
`arcgisSearchComplete`	CustomEvent<SearchResponse>
`arcgisSearchStart`	CustomEvent<SearchViewModelEvents["search-start"]>
`arcgisSelectResult`	CustomEvent<SearchViewModelSelectResultEvent>
`arcgisSuggestComplete`	CustomEvent<SearchViewModelEvents["suggest-complete"]>
`arcgisSuggestStart`	CustomEvent<SearchViewModelEvents["suggest-start"]>

arcgisPropertyChange

Event

arcgisPropertyChange: CustomEvent<{ name: "state"; }>

Emitted when the value of a property is changed. Use this to listen to changes to properties.

arcgisReady

Event

arcgisReady: CustomEvent<void>

Emitted when the component associated with a map or scene view is ready to be interacted with.

arcgisSearchClear

Event

arcgisSearchClear: CustomEvent<SearchViewModelEvents["search-clear"]>

Fires when a result is cleared from the input box or a new result is selected.

arcgisSearchComplete

Event

arcgisSearchComplete: CustomEvent<SearchResponse>

Fires when the search() method is called and returns its results.

arcgisSearchStart

Event

arcgisSearchStart: CustomEvent<SearchViewModelEvents["search-start"]>

Fires when the search() method starts.

arcgisSelectResult

Event

arcgisSelectResult: CustomEvent<SearchViewModelSelectResultEvent>

Fires when a search result is selected.

arcgisSuggestComplete

Event

arcgisSuggestComplete: CustomEvent<SearchViewModelEvents["suggest-complete"]>

Fires when the suggest() method is called and returns its results.

arcgisSuggestStart

Event

arcgisSuggestStart: CustomEvent<SearchViewModelEvents["suggest-start"]>

Fires when the suggest() method starts.