Choose a version:

Web components

Polaris provides a library of web components for your app to display data, get input from merchants, and trigger API calls. These components follow Shopify's design system, ensuring that your app looks and feels native to the Shopify admin.

Anchor to Adding Polaris to your appAdding Polaris to your app

When you scaffold your app using Shopify CLI, Polaris is added to your app automatically, set up with polaris-1.js to follow the newest stable release of Polaris version 1. The snippets on this page load polaris-1.1-rc.js instead, because this reference documents the 1.1 release candidate.

You can also manually add Polaris in any framework by adding a script tag to your app's HTML head. There are two kinds of URL to choose between:

polaris-1.1-rc.js names a specific release, the 1.1 release candidate that this reference documents. Load it to build against the components described here.
polaris-1.js is a channel. It always serves the newest stable release in Polaris 1, and it's what we recommend for production.

To build against the components this reference documents, load the release candidate:

<head>

</head>

// app/root.tsx

export default function App() {

return (

<html>

<head>

</head>

</html>

);

}

HTML

<head>
  <meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
  <script src="https://cdn.shopify.com/shopifycloud/polaris-1.1-rc.js"></script>
</head>

Remix

// app/root.tsx
export default function App() {
  return (
    <html>
      <head>
        <meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
        <script src="https://cdn.shopify.com/shopifycloud/polaris-1.1-rc.js" />
      </head>
    </html>
  );
}

For production, load the stable channel instead:

<head>

</head>

// app/root.tsx

export default function App() {

return (

<html>

<head>

</head>

</html>

);

}

HTML

<head>
  <meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
  <script src="https://cdn.shopify.com/shopifycloud/polaris-1.js"></script>
</head>

Remix

// app/root.tsx
export default function App() {
  return (
    <html>
      <head>
        <meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
        <script src="https://cdn.shopify.com/shopifycloud/polaris-1.js" />
      </head>
    </html>
  );
}

The following table shows the different options for configuring your script tag and the version of the library that is served.

Script tag	Serves	Notes
`polaris-1.js`	The newest stable release in Polaris 1, currently 1.0	Advances each time a new 1.x release goes stable
`polaris-1.1-rc.js`	The 1.1 release candidate	Accumulates compatible changes and bug fixes until 1.1 goes stable
`polaris-1.1.js`	Polaris 1.1, once its release candidate is promoted	Security fixes only
`polaris-1.0.js`	Polaris 1.0, released in 2025	Frozen as released
`polaris.js`	The legacy unversioned entry point, currently 1.0	Advances to 1.1 when 1.1 goes stable, then tracks 1.x. Never serves 2.x

Anchor to Stable releases and release candidatesStable releases and release candidates

For production, we recommend the stable channel, polaris-1.js. It always serves the newest stable release in Polaris 1, so bug fixes, accessibility improvements, and new components reach your app without a script-tag change.

Each stable release is also published at its own URL, like polaris-1.0.js and, once 1.1 is promoted, polaris-1.1.js. Published stable versions are immutable except for critical security fixes, ensuring that your app continues using the version of the library you tested against. If you need to control exactly when your app moves, name a specific version instead of the channel.

Promotion doesn't update the release candidate URL in place. The stable release publishes at its own URL instead, so moving to it is a change you make in your app's code: update the script tag to polaris-1.1.js for that release, or to polaris-1.js to follow the channel.

For the fuller story on how Polaris is versioned on the CDN, see The Polaris CDN is adopting semantic versioning.

Anchor to Available componentsAvailable components

Anchor to ActionsActions

Action components let users trigger events, perform tasks, and navigate through the interface.

Button

Trigger actions or events, such as submitting forms, opening dialogs, or navigating to other pages.

Button group

Display multiple buttons in a layout.

Clickable

Create custom interactive elements not achievable with Button or Link.

Clickable chip

Categorize or highlight content attributes with an interactive button.

Link

Make text interactive for navigating to other pages or performing actions.

Display a list of actions that can be performed on a resource.

Anchor to Feedback and status indicatorsFeedback and status indicators

Feedback and status indicators display information about the status of resources and actions.

Badge

Inform users about the status of a resource or indicate that an action has been completed.

Banner

Highlight important information or required actions prominently within the interface.

Empty state

Explain why a page, list, or table has nothing to show and offer the next action.

Spinner

Display an animated indicator showing users that content or actions are loading.

Anchor to FormsForms

Form components capture user input with built-in validation and formatting.

Checkbox

Give users a clear way to make selections, such as agreeing to terms or choosing multiple items.

Choice list

Present multiple options for single or multiple selections.

Color field

Let users select a color with a color picker or as a text input.

Color picker

Let users select a color from a color palette.

Date field

Let users select a specific date with a date picker.

Date picker

Let users select a specific date or date range.

Drop zone

Let users upload files through drag-and-drop functionality or by activating a button.

Email field

Let users enter email addresses with optimized keyboard settings.

Money field

Collect monetary values from users with built-in currency formatting and validation.

Number field

Collect numerical values from users with optimized keyboard settings and built-in validation.

Password field

Securely collect sensitive information from users.

Search field

Let users enter search terms using a single-line input field.

Select

Let users pick one option from a menu.

Switch

Give users a clear way to toggle options on or off.

Text area

Collect longer text content from users with a multi-line input.

Text field

Let users enter or edit text within a single-line input.

URL field

Collect URLs from users with built-in formatting and validation.

Anchor to Layout and structureLayout and structure

Layout components create consistent visual hierarchy and organize content into clear structures.

Box

Provide a flexible container for custom designs not achievable with existing components.

Divider

Create clear visual separation between elements.

Grid

Organize content in a matrix of rows and columns for responsive layouts.

Ordered list

Display a numbered list of related items in a specific sequence.

Page

Use as the main container for placing content in your app with preset layouts and automatic spacing between elements.

Query container

Establish a query container for responsive design.

Section

Group related content into clearly-defined thematic areas.

Stack

Organize elements horizontally or vertically along the block or inline axis.

Table

Display data clearly in rows and columns for viewing, analyzing, and comparing information.

Unordered list

Display a bulleted list of related items.

Anchor to Media and visualsMedia and visuals

Media and visual components display images, icons, and visual elements that enhance the interface.

Avatar

Show a user's profile image or initials in a compact, visual element.

Icon

Render a graphic symbol to visually communicate core parts of the interface and available actions.

Image

Embed an image within the interface and control its presentation.

Thumbnail

Display a small preview image representing content, products, or media.

Anchor to OverlaysOverlays

Overlay components display content above the page in focused, contextual layers.

Modal

Display content in a focused overlay that blocks page interaction until dismissed.

Popover

Display content in an overlay anchored to a trigger element without blocking page interaction.

Anchor to Typography and contentTypography and content

Typography components display and format text content with consistent styling.

Chip

Represent user-supplied keywords that help label, organize, and categorize objects.

Heading

Render hierarchical titles to communicate the structure and organization of page content.

Number

Display inline numeric values with tabular numerals so figures line up in columns.

Paragraph

Display a block of text that can contain inline elements such as buttons, links, or emphasized text.

Text

Display inline text with specific visual styles or tones.

Tooltip

Display helpful information in a small overlay when users hover or focus on an element.

Was this page helpful?