Migrate EmptySearchResult from Polaris React

Replace Polaris React EmptySearchResult with s-empty-state after a completed search or filter query returns no matches. Keep the query controls visible and use the primary action to clear or broaden the query.

s-empty-state is available in Polaris 1.1 and later. The stable channel, polaris-1.js, includes it; install @shopify/polaris-types@^1.1.0 alongside it. If you pin polaris-1.1.js instead, use @shopify/polaris-types@~1.1.0 so the types stay on 1.1 like the script tag.

Anchor to Choose the destinationChoose the destination

Polaris React	Polaris web components	Migration type
`EmptySearchResult`	`s-empty-state`	Direct

Anchor to Map the empty search resultMap the empty search result

Polaris React	Polaris web components	Migration notes
`title`	`heading`	Include the active query when it helps merchants understand why no results appear.
`description`	`s-text` in the `subheading` slot	Suggest a concrete next step, such as changing filters or clearing the search.
`withIllustration`	Optional `s-icon` or `s-image` in the `graphic` slot	Omit the graphic in dense tables. If used, keep it decorative unless it communicates information not present in the text.
Search and filter state	Keep controls outside `s-empty-state`; add a clear action in `primary-action`	Clear the same state used to build the backend request, then request the unfiltered results.

Anchor to Migrate the call siteMigrate the call site

Keep search and filter controls mounted while the completed request has no results.
Render s-empty-state only when the request has completed and the filtered result set is empty.
Connect the clear action to all applied query state and trigger the same data-loading path used by the controls.
After verification, remove the EmptySearchResult import and any Polaris-only state, wrappers, or helpers that no longer have a caller.

Anchor to Preserve these behaviorsPreserve these behaviors

The current query and applied filters remain visible.
Clearing the query updates both the controls and backend results.
Loading, empty, populated, and error states remain mutually exclusive.

Anchor to Test and remove Polaris ReactTest and remove Polaris React

Test a query with no matches, clear it, and verify that the controls and results update together. Confirm that the empty state doesn't replace loading or error feedback and remains usable at narrow widths.

Don't remove @shopify/polaris while another component still imports it. Once all call sites are migrated, remove the package and its provider-level setup, then run the app's full test suite.

Anchor to Migration exampleMigration example

Migrating EmptySearchResult

import {useState} from 'react';

export function EmptySearchResultMigrationExample() {

const [query, setQuery] = useState('snowboard boots');

return (

<s-stack gap="base">

<s-search-field

label="Search products"

value={query}

onInput={(event) => setQuery(event.currentTarget.value)}

<s-empty-state heading={`No products found for “${query}”`}>

<s-icon slot="graphic" type="search" />

<s-text slot="subheading">

Try another search or clear the current query.

</s-text>

<s-button

slot="primary-action"

variant="primary"

onClick={() => setQuery('')}

Clear search

</s-button>

</s-empty-state>

</s-stack>

);

}

import {EmptySearchResult} from '@shopify/polaris';

export function EmptySearchResultMigrationExample() {

return (

);

}

Polaris web components

// @validate-ignore: Property 's-empty-state' does not exist on type 'JSX.IntrinsicElements'
import {useState} from 'react';

export function EmptySearchResultMigrationExample() {
  const [query, setQuery] = useState('snowboard boots');

  return (
    <s-stack gap="base">
      <s-search-field
        label="Search products"
        value={query}
        onInput={(event) => setQuery(event.currentTarget.value)}
      />
      <s-empty-state heading={`No products found for “${query}”`}>
        <s-icon slot="graphic" type="search" />
        <s-text slot="subheading">
          Try another search or clear the current query.
        </s-text>
        <s-button
          slot="primary-action"
          variant="primary"
          onClick={() => setQuery('')}
        >
          Clear search
        </s-button>
      </s-empty-state>
    </s-stack>
  );
}

Polaris React

import {EmptySearchResult} from '@shopify/polaris';


export function EmptySearchResultMigrationExample() {

  return (
    <EmptySearchResult title="No products found" description="Try changing the filters." withIllustration />
  );
}

Preview

Was this page helpful?