preetamnath/polaris-web-components

Polaris Web Components

Component catalog, rules, and patterns for polaris-app-home. MCP tool calls (doc search, validation) route through /shopify-dev-mcp.

Rules

• Never use deprecated components. Use the recommended replacement.
• <s-link> is for navigation only. Never use <s-link> for actions. Use <s-button> or <s-clickable> instead.
• showOverlay() / hideOverlay() are DOM methods, not App Bridge. Call these on <s-modal> and <s-popover> element refs directly (e.g., document.getElementById('my-modal')?.showOverlay()). They are NOT shopify.* APIs.
• SpacingKeyword / SizeKeyword scale. Numbers increase with size: small-500 (smallest) → small-400 → small-300 → small-200 → small-100 → small → base → large → large-100 → large-200 → large-300 → large-400 → large-500 (largest). Used by gap, padding, border size, etc. none is also valid for spacing/padding.

Instructions

1. Find component in the Component Catalog. If missing, invoke /shopify-dev-mcp → search_docs_chunks with api_name: "polaris-app-home". Do NOT use fetch_full_docs for this surface (deprecated).
2. Write markup following the rules above and Common Patterns.
3. Validate via /shopify-dev-mcp → validate_component_codeblocks with api: "polaris-app-home". If validation fails twice on the same artifact, stop and surface the error to the user.

Common Patterns

Copy-paste friendly patterns from this codebase.

Icon-only button

Tertiary button with just an icon — used for delete, edit, collapse, etc.

<s-button variant="tertiary" tone="critical" icon="delete" accessibilityLabel="Remove item" onClick={handleRemove} />

Collapsible box

Toggle content visibility without unmounting. Uses <s-box display> with the undefined omission pattern.

<s-box display={expanded ? undefined : 'none'}>
  {/* content stays mounted, just hidden */}
</s-box>

Inline divider with label

Horizontal rule with a centered text label (AND/OR separators). Requires style={{ flex: 1 }} on dividers — no native prop for this.

<div style={{ display: 'flex', alignItems: 'center', gap: 'var(--p-space-300, 12px)' }}>
  <s-divider style={{ flex: 1 }} />
  <s-text color="subdued" type="strong">OR</s-text>
  <s-divider style={{ flex: 1 }} />
</div>

---

<!-- source: references/polaris-app-home-catalog.md -->

Component Catalog

Layout & Structure

| Element | Purpose | Key Props / Gotchas | |---------|---------|---------------------| | <s-app> | Root app wrapper | Must be outermost <s-*> element. One per app. | | <s-page> | Page container | heading (NOT title). Slots: primary-action, secondary-actions, aside, breadcrumb-actions, accessory. inline-size: small/base/large. | | <s-section> | Content card/group | heading attr. padding: base (default) / none (full-bleed for tables). accessibilityLabel for headingless sections. slot="aside" on page for sidebar. Only slot is children — no description or other named slots. Top-level sections = cards; nested sections = plain. | | <s-stack> | Flex layout | direction: inline (row) / block (column, default). gap (SpacingKeyword — no default, always set explicitly). alignItems, alignContent, justifyContent. Has all Box props. Implicit flex-wrap — no wrap prop. | | <s-grid> | CSS grid layout | gridTemplateColumns (NOT columns) — CSS track values: "1fr auto", "repeat(3, 1fr)". gridTemplateRows — same syntax. gap / columnGap / rowGap (SpacingKeyword). alignItems, justifyContent, alignContent, justifyItems. Has all Box props. Child <s-grid-item> uses gridColumn / gridRow (e.g. gridColumn="span 2"). | | <s-box> | Passive container | padding / paddingBlock / paddingInline (PaddingKeyword: none / small-100..large-500 / base). background (BackgroundColorKeyword: transparent / subdued / base / strong). border: "size" or "size color" or "size color style" (e.g. border="base subdued dashed"). borderRadius (none / small / small-100 / small-200 / base / large / large-100 / large-200). display (auto / none) for collapsible patterns. overflow (visible / hidden). inlineSize / blockSize / maxInlineSize / minInlineSize (SizeUnits or auto). No flex/grid layout props. | | <s-divider> | Visual separator | direction="inline" = horizontal (default). direction="block" = vertical. | | <s-app-nav> | Sidebar navigation | Uses <s-link> children. Example: <s-app-nav><s-link href="/funnels" rel="home">Home</s-link></s-app-nav>. | | <s-query-container> | CSS container query context | containerName attr. Establishes a @container context for responsive child layouts. |

Typography & Content

| Element | Purpose | Key Props / Gotchas | |---------|---------|---------------------| | <s-heading> | Section heading | Auto-levels based on nesting inside <s-section>. | | <s-text> | Inline styled text | type: generic / strong / address / redundant. No fontWeight attribute — use type="strong" for bold, full stop. color: base / subdued. tone: auto / neutral / info / success / warning / critical / caution. Renders inline — wrap in <s-paragraph> or <s-stack> to stack vertically. | | <s-paragraph> | Block text | tone, color="subdued". Contains inline elements like <s-text>, <s-link>. | | <s-chip> | Static display tag | color (base/subdued/strong). Non-interactive. | | <s-tooltip> | Hover/focus hint | id required + interest-for on trigger element (NOT command-for). |

Actions

| Element | Purpose | Key Props / Gotchas | |---------|---------|---------------------| | <s-button> | Actions, form submit, links | variant for styling (primary/secondary/tertiary), NOT type. type is form behavior (submit/button/reset). icon for leading icon (icon-only: omit text content, add accessibilityLabel). tone: auto/critical. command-for + command to trigger overlays. | | <s-link> | Text links | Navigation only — triggers page transitions. Never for actions (use <s-button>/<s-clickable>). Inside <s-app-nav> for sidebar. | | <s-clickable> | Generic clickable area | Renders <a> with href/target/download, <button> without. Full box-model props like <s-box>: border, borderRadius, background, padding, display, inlineSize, overflow. loading boolean. commandFor + command to trigger overlays. disabled boolean. Use for custom interactive cards/regions when <s-button> or <s-link> don't fit. | | <s-menu> | Action list dropdown | Needs id + command-for on trigger button. Accepts <s-button> and <s-section> children. | | <s-clickable-chip> | Interactive filter/tag chip | removable for dismiss; color (base/subdued/strong); command-for supported. | | <s-button-group> | Grouped buttons in structured layout | gap: base/none only (NOT full SpacingKeyword). Slots: primary-action, secondary-actions, children. |

Forms

| Element | Purpose | Key Props / Gotchas | |---------|---------|---------------------| | <s-text-field> | Single-line text input | icon for leading icon. accessory slot for trailing content. prefix/suffix string attrs for inline text. details for helper text below field. labelAccessibilityVisibility="exclusive" to visually hide label. onInput fires every keystroke; onChange fires on blur/Enter. | | <s-text-area> | Multi-line text input | rows, max-length. onInput fires every keystroke; onChange fires on blur/Enter. | | <s-checkbox> | Single boolean toggle | label required. value attr for form data. | | <s-choice-list> | Radio/checkbox group | Contains <s-choice> children. multiple for checkboxes, omit for radios. label (field label). values (array of selected values). details for helper text. onChange returns e.target.values (string array). | | <s-choice> | Individual option in choice-list | value + selected attrs. defaultSelected for uncontrolled default. accessibilityLabel replaces visible label for screen readers. Slots: details (subtitle below label), secondary-content (rich content — text fields, buttons, etc. below the choice). | | <s-number-field> | Numeric input | label, min, max, step, value, inputMode (numeric/decimal). prefix/suffix for inline text (e.g. $). details for helper text. onInput fires every keystroke; onChange fires on blur/Enter. | | <s-select> | Dropdown select | Contains <s-option> children. placeholder for default text. | | <s-switch> | Toggle switch | label + checked boolean. details for helper text. error, disabled, required. defaultChecked for uncontrolled. | | <s-drop-zone> | File upload area | accept for file types, multiple for multi-file. | | <s-date-field> | Date text input | allow restricts date range (e.g., "2025--"). | | <s-url-field>, <s-email-field>, <s-password-field>, <s-search-field>, <s-color-field>, <s-color-picker>, <s-date-picker> | Typed text-field variants — share label/placeholder with <s-text-field>. Use when input type matters for validation/autocomplete. |

Feedback & Status

| Element | Purpose | Key Props / Gotchas | |---------|---------|---------------------| | <s-banner> | Prominent message/alert | heading (NOT title). tone (info/success/warning/critical). dismissible boolean. Slot secondary-actions for buttons (max 2). hidden to control visibility. | | <s-badge> | Status label/tag | tone: success/warning/critical/info/neutral/caution. color: base/subdued/strong. icon attr. | | <s-spinner> | Loading indicator | size: base/large/large-100 (NO small). accessibility-label required. |

<s-skeleton-body-text> does NOT exist as a web component. Never generate it. Use <s-spinner> for loading states.

Media & Visuals

| Element | Purpose | Key Props / Gotchas | |---------|---------|---------------------| | <s-icon> | Graphic symbol | type (icon name: "cart", "delete", "check-circle", "product", "collection", etc.). tone: auto/neutral/info/success/warning/critical. color: base/subdued. size: small/base only (no large). interestFor to link to a <s-tooltip> by id. | | <s-image> | Responsive image | aspect-ratio, object-fit, loading="lazy" attrs. | | <s-thumbnail> | Small preview image | src, alt. Sizes: small/small-200/small-100/base/large/large-100. | | <s-avatar> | User/entity avatar | initials, src, alt. Sizes: small/small-200/base/large/large-200. |

Embedded Surfaces

| Element | Purpose | Key Props / Gotchas | |---------|---------|---------------------| | <s-app-window> | Embedded app iframe | id required. src for iframe URL (required). Imperative API via ref: .show() / .hide() / .toggle(). Fires both show and hide events. Used for live previews (e.g., offer preview in OfferStep). |

Overlays

| Element | Purpose | Key Props / Gotchas | |---------|---------|---------------------| | <s-popover> | Contextual overlay | id required + command-for on trigger button. inline-size for width (e.g., "300px"). Also block-size, max-inline-size, max-block-size. No heading prop (unlike <s-modal>). | | <s-modal> | Dialog overlay | heading (NOT title). id required + command-for on trigger button. Slots: primary-action, secondary-actions. size: small/small-100/base/large/large-100. padding="none" for full-bleed content. command="--hide" on inner buttons to close. |

Table

| Element | Purpose | Key Props / Gotchas | |---------|---------|---------------------| | <s-table> | Data table container | variant="auto" for responsive. Wrap in <s-section padding="none"> for full-width. paginate/hasNextPage/hasPreviousPage props. Events: nextpage/previouspage. filters slot for table filters. | | <s-table-header> | Column header | list-slot (primary/labeled/inline/secondary) controls responsive behavior. format="numeric" or "currency" for alignment. |

App Bridge APIs

| API | Purpose | Usage | |-----|---------|-------| | Toast | Transient messages | shopify.toast.show('Saved') | | Modal API | Programmatic overlay control | DOM methods on <s-modal> / <s-popover> elements: el.showOverlay() / el.hideOverlay() | | Save Bar | Unsaved form changes bar | data-save-bar on form + <ui-save-bar> | | Resource Picker | Product/collection picker | shopify.resourcePicker() | | Navigation | URL management | Managed via <s-app-nav> + App Bridge | | Loading | Global loading bar | Title bar loading indicator | | ID Token | Session token for API calls | shopify.idToken() | | App Window | Programmatic app window control | shopify.appWindow.hide() — bridge API separate from <s-app-window> element |