Polaris web component autocomponents are built using Shopify's Polaris web components design system and are designed to be used in Shopify apps. Unlike the React-based Polaris autocomponents, these use Shopify's web component system, such as <s-page>, <s-section>, and <s-text>, which are loaded via a <script> tag. No React wrapper or AppProvider is needed.
Polaris web components work by including a single script tag that registers custom HTML elements prefixed with s- in the browser. These elements render Shopify's Polaris UI directly in the DOM, and can be used alongside React components seamlessly.
For more information on the autocomponents, see the @gadgetinc/react/auto references.
Installing
Newly created Shopify apps use Polaris web components by default. For existing apps, follow the steps below to migrate.
Step 1: Ensure you have the correct Gadget dependencies
@gadgetinc/react must be at least version 0.25.0 to use Polaris web components based autocomponents, and @gadgetinc/react-shopify-app-bridge must be at least version 0.21.2.
These packages can be easily updated using the Update Gadget-provided npm packages command in the Gadget Editor.
Step 2: Add the Polaris web components script tag
Polaris web components are loaded via a script tag from Shopify's CDN. Where you add this depends on your app's routing setup:
For file-based routing apps using Remix or React Router, add the script tag to the <head> in your root layout file, such as web/root.tsx:
Add "@shopify/app-bridge-types" and "@shopify/polaris-types" to the compilerOptions.types array in your TypeScript config so that the custom <s-*> elements are recognized by TypeScript and your editor.
If your project has a tsconfig.web.json file, update that file. Otherwise, update tsconfig.json.
tsconfig.web.json (or tsconfig.json if tsconfig.web.json does not exist)
json
{
"compilerOptions": {
"types": [
// ... other types ...
"@shopify/app-bridge-types",
"@shopify/polaris-types"
// ... other types ...
]
}
}
Step 5: Remove the Polaris React provider
If your app currently uses the React-based Polaris components, you can remove the AppProvider wrapper and related imports. Polaris web components do not require a React provider. They work as soon as the script tag is loaded.
Remove the following from your root layout or main.tsx:
React
// Remove these imports
import { AppProvider } from "@shopify/polaris";
import "@shopify/polaris/build/esm/styles.css";
import enTranslations from "@shopify/polaris/locales/en.json";
// Remove these imports
import { AppProvider } from "@shopify/polaris";
import "@shopify/polaris/build/esm/styles.css";
import enTranslations from "@shopify/polaris/locales/en.json";
And remove the <AppProvider> wrapper from your component tree.
Note that this requires you to fully migrate your app from Polaris React to Polaris web components.
Usage
Import Shopify Polaris web component autocomponents from @gadgetinc/react/auto/polaris-wc:
React
import { AutoForm, AutoTable, AutoInput, AutoSubmit } from "@gadgetinc/react/auto/polaris-wc";
import { AutoForm, AutoTable, AutoInput, AutoSubmit } from "@gadgetinc/react/auto/polaris-wc";
For example, to use the AutoForm component:
React
import { AutoForm, AutoInput, AutoSubmit } from "@gadgetinc/react/auto/polaris-wc";
import { api } from "../api";
export default function () {
return (
<AutoForm action={api.widget.create}>
<AutoInput field="name" />
<AutoSubmit />
</AutoForm>
);
}
import { AutoForm, AutoInput, AutoSubmit } from "@gadgetinc/react/auto/polaris-wc";
import { api } from "../api";
export default function () {
return (
<AutoForm action={api.widget.create}>
<AutoInput field="name" />
<AutoSubmit />
</AutoForm>
);
}
For all field types, there are field type-specific input components that have additional props you can use to further customize the inputs.
example using Polaris params on an AutoStringInput
React
import { AutoForm, AutoStringInput, AutoSubmit } from "@gadgetinc/react/auto/polaris-wc";
import { api } from "../api";
export default function () {
return (
<AutoForm action={api.widget.create}>
<AutoStringInput field="name" onFocus={() => console.log("focused")} />
<AutoSubmit />
</AutoForm>
);
}
import { AutoForm, AutoStringInput, AutoSubmit } from "@gadgetinc/react/auto/polaris-wc";
import { api } from "../api";
export default function () {
return (
<AutoForm action={api.widget.create}>
<AutoStringInput field="name" onFocus={() => console.log("focused")} />
<AutoSubmit />
</AutoForm>
);
}
Custom action Polaris web component modal
To render a custom popup when a user selects an action, create a custom action and use it to show a modal:
action with a custom render
React
import { AutoTable } from "@gadgetinc/react/auto/polaris-wc";
import { api } from "../api";
import { Modal, TitleBar, useAppBridge } from "@shopify/app-bridge-react";
export default function () {
const shopify = useAppBridge();
return (
<>
<AutoTable
model={api.product}
actions={[
{
label: "Export",
action: async (records) => {
// show the modal when the action is clicked
shopify.modal.show("my-modal");
},
},
]}
/>
{/** use the Shopify AppBridge modal component */}
<Modal id="my-modal">
<p>Message</p>
<TitleBar title="My modal">
<button onClick={() => shopify.modal.hide("my-modal")}>Close</button>
</TitleBar>
</Modal>
</>
);
}
import { AutoTable } from "@gadgetinc/react/auto/polaris-wc";
import { api } from "../api";
import { Modal, TitleBar, useAppBridge } from "@shopify/app-bridge-react";
export default function () {
const shopify = useAppBridge();
return (
<>
<AutoTable
model={api.product}
actions={[
{
label: "Export",
action: async (records) => {
// show the modal when the action is clicked
shopify.modal.show("my-modal");
},
},
]}
/>
{/** use the Shopify AppBridge modal component */}
<Modal id="my-modal">
<p>Message</p>
<TitleBar title="My modal">
<button onClick={() => shopify.modal.hide("my-modal")}>Close</button>
</TitleBar>
</Modal>
</>
);
}