Using Polaris web components

Polaris web components are Shopify’s UI toolkit for building interfaces that match the Shopify Checkout design system. This toolkit provides a set of custom HTML elements (web components) that you can use to create consistent, accessible, and performant user interfaces for the Checkout UI Extensions.

Choose a version:

Anchor to StylingStyling

Polaris web components come with built-in styling that follows Shopify’s design system. The components will automatically apply the correct styling based on the properties you set and the context in which they are used. For example, headings automatically display at progressively less prominent sizes based on how many levels deep they are nested inside of sections. All components inherit a merchant’s brand settings and the CSS cannot be altered or overridden.

Anchor to Custom layoutCustom layout

When you need to build custom layouts you can use s-stack, s-grid and s-box.

s-stack and s-grid do not include spacing between children by default. To apply white space between children use the gap property
When s-stack is direction="inline" it will automatically wrap children to a new line when space is limited.
s-grid will allow children to overflow unless template rows/columns are properly set.
Order is important for shorthand properties, e.g. border takes size-keyword, color-keyword, style-keyword

Anchor to ScaleScale

Our components use a middle-out scale for multiple properties like padding, size and gap.

Our scale moves from the middle out:

small-300 is smaller than small-100
large-300 is bigger than large-100
small-100 and large-100 have aliases of small and large
base is the default value

Anchor to Responsive valuesResponsive values

Some properties accept responsive values, which enables you to change the value of the property depending on a parent inline size.

Syntax

The syntax for a responsive value generally follows the ternary operator syntax. For example, @container (inline-size > 500px) large, small means that the value will be large if the container is more than 500px wide, and small if the container is 500px or less. The syntax rules are:

Begin the value with @container
Optionally add a name to target a specific container
Use the inline-size keyword inside of parentheses to query the inline-size of the container. This is the condition that will be evaluated to determine which value to use.
Set the value if that condition is true
Set the value to be used if the condition is false.

For greater compatibility on older browsers, container queries must follow a mobile-first approach. The fallback value (when the condition is false) must always represent your smallest supported design, with the condition value (when the condition is true) providing styles for larger containers. For example, <Stack direction="@container (inline-size > 300px) inline, block"> ensures that browsers that do not support container styles get a design that works in all container sizes.

Using s-query-container

When using responsive values, you must also place the <s-query-container> component in the location you want to query the inline-size.

By default, the responsive value will query against the closest parent; to look up a specific parent, this component also accepts a containername attribute which adds a name to the container. Then add that name after @container in your responsive query to target it.

Values with reserved characters

Some values could contain reserved characters used in the responsive value syntax, such as () or ,. To use these values, escape them by wrapping them in quotes.

Advanced patterns

The syntax is flexible enough to support advanced patterns such as compound conditions, and|or conditions, and nested conditions.

HTML

<s-box

padding="@container (inline-size > 500px) large-400, small"

This padding will be "large-400" when the

container is more than 500px. Otherwise it will

be "small".

</s-box>

Pseudocode

<s-query-container>

<s-box padding="@container (inline-size > 500px) large-400, small">

This padding will be "large-400" when the container is more than 500px.

Otherwise it will be "small".

</s-box>

</s-query-container>

<s-query-container containername="outer">

<s-section>

<s-query-container>

<s-box padding="@container outer (inline-size > 500px) large-400, small">

This padding will be "large-400" when the "outer" container is more than 500px.

Otherwise it will be "small".

</s-box>

</s-query-container>

</s-section>

</s-query-container>

Basic example

<s-query-container>
  <s-box padding="@container (inline-size > 500px) large-400, small">
    This padding will be "large-400" when the container is more than 500px.
    Otherwise it will be "small".
  </s-box>
</s-query-container>

Named example

<s-query-container containername="outer">
  <s-section>
    <s-query-container>
      <s-box padding="@container outer (inline-size > 500px) large-400, small">
        This padding will be "large-400" when the "outer" container is more than 500px.
        Otherwise it will be "small".
      </s-box>
    </s-query-container>
  </s-section>
</s-query-container>

Advanced patterns

<s-query-container>

<s-box padding="@container (300px < inline-size < 500px) small, large-500">

The padding will be "small" when the container is between 300px and 500px

wide. Otherwise it will be "large-500".

</s-box>

</s-query-container>

<s-query-container>

<s-box

padding="@container (inline-size > 500px) and (inline-size < 1000px) large-400, small"

This padding will be "large-400" when the container is more than 500px wide and

when the container is smaller than 1000px wide. Otherwise it will be

"small".

</s-box>

</s-query-container>

<s-query-container>

<s-box

padding="@container (inline-size > 500px) base, (inline-size > 1000px) large-400, small"

This padding will be "base" when the container is greater than 500px wide,

"large-400" when the container is larger than 1000px wide, and "small" otherwise.

</s-box>

</s-query-container>

Compound

<s-query-container>
  <s-box padding="@container (300px < inline-size < 500px) small, large-500">
    The padding will be "small" when the container is between 300px and 500px
    wide. Otherwise it will be "large-500".
  </s-box>
</s-query-container>

And|or

<s-query-container>
  <s-box
    padding="@container (inline-size > 500px) and (inline-size < 1000px) large-400, small"
  >
    This padding will be "large-400" when the container is more than 500px wide and
    when the container is smaller than 1000px wide. Otherwise it will be
    "small".
  </s-box>
</s-query-container>

Nested

<s-query-container>
  <s-box
    padding="@container (inline-size > 500px) base, (inline-size > 1000px) large-400, small"
  >
    This padding will be "base" when the container is greater than 500px wide,
    "large-400" when the container is larger than 1000px wide, and "small" otherwise.
  </s-box>
</s-query-container>

Anchor to Interactive elementsInteractive elements

s-button, s-link and s-clickable render as anchor elements when they have a href and render as a button element when they have an onClick without a href. The HTML specification states that interactive elements cannot have interactive children.

s-clickable is an escape hatch for when s-link and s-button are not able to implement a specific design. You should always try to use s-link and s-button first.

Interactive components with target="auto" automatically use _self for internal links and _blank for external URLs. This behavior ensures a consistent navigation experience for users without requiring developers to manually set the correct target for each link.

Anchor to Variant tone and colorVariant tone and color

The tone is used to apply a group of color design tokens to the component such as critical, success or info.

The color adjusts the intensity of the tone making it more subdued or strong.

The variant is used to change how the component is rendered to match the design language this is different for each component.

Anchor to Using with PreactUsing with Preact

For UI Extensions, Shopify provides Preact as the framework of choice. Using Polaris web components with Preact is very similar to using them with React.

Anchor to Properties vs attributesProperties vs attributes

Polaris web components follow the same property and attribute patterns as standard HTML elements. Understanding this distinction is important for using the components effectively.

Key concepts

Attributes are HTML attributes that appear in the HTML markup.
Properties are JavaScript object properties accessed directly on the DOM element.
Most attributes in Polaris web components are reflected as properties, with a few exceptions like value and checked which follow HTML’s standard behavior.

How JSX properties are applied

When using Polaris web components in JSX, the framework determines how to apply your props based on whether the element has a matching property name.

If the element has a property with the exact same name as your prop, the value is set as a property. Otherwise, it’s applied as an attribute. Here’s how this works in pseudocode:

Examples

For Polaris web components, you can generally just use the property names as documented, and everything will work as expected.

Anchor to Event HandlingEvent Handling

Polaris web components use standard DOM events, making them work seamlessly with your preferred framework. You can attach event handlers using the same patterns as with native HTML elements.

Basic Event Handling

Event handlers in Polaris components work just like standard HTML elements. In frameworks, use the familiar camelCase syntax (like onClick in Preact). In plain HTML, use lowercase attributes or addEventListener.

Form Input Events

Polaris form components support two primary event types for tracking input changes:

onInput: Fires immediately on every keystroke or value change
onChange: Fires when the value is committed; for text fields that happens on blur; for checkboxes and radio buttons immediately after onInput.

Choose the appropriate event based on your needs:

Use onInput for real-time validation or character counting
Use onChange for validation after a user completes their input

Focus Management

Track when users interact with form elements using these events:

onFocus: Fires when an element receives focus
onBlur: Fires when an element loses focus

Form Values and Types

Important details about form values in Polaris web components:

All form elements return string values in their events, even numeric inputs
Multi-select components (like s-choice-list) use a values prop (array of strings)
Access values in event handlers via event.currentTarget.value

Controlled vs. Uncontrolled Components

Polaris components can be used in two ways: Uncontrolled (simpler): Component manages its own internal state - use defaultValue prop Controlled (more powerful): Your code manages the component’s state - use value prop

Use controlled components when you need to:

Validate input as the user types
Format or transform input values
Synchronize multiple inputs

Technical Details

Under the hood, Polaris web components handle event registration consistently across frameworks:

In Preact, Polaris components properly register events via addEventListener instead of setting attributes
Event names are automatically converted to lowercase (onClick becomes click)
All event handlers receive standard DOM events as their first argument

For example, when you write <s-button onClick={handleClick}>, the component:

Sees that "onclick" in element is true
Registers your handler via addEventListener('click', handler)
Passes the event object to your handler when clicked

Basic Event Handling Examples

<s-button onClick={() => console.log('Clicked!')}>

Inline Handler

</s-button>

<s-button onClick={(event) => {

console.log('Event details:', event.type);

console.log('Target:', event.currentTarget);

}}>

With Event Object

</s-button>

<s-button onclick="console.log('Button clicked!')">

Click me

</s-button>

<s-button id="eventButton">

Click me (addEventListener)

</s-button>

const eventButton = document.getElementById('eventButton');

eventButton.addEventListener('click', () => {

console.log('Button clicked via addEventListener!');

});

</script>

JSX

<s-button onClick={() => console.log('Clicked!')}>
  Inline Handler
</s-button>

<s-button onClick={(event) => {
  console.log('Event details:', event.type);
  console.log('Target:', event.currentTarget);
}}>
  With Event Object
</s-button>

HTML

<s-button onclick="console.log('Button clicked!')">
  Click me
</s-button>

<s-button id="eventButton">
  Click me (addEventListener)
</s-button>

<script>
  const eventButton = document.getElementById('eventButton');

  eventButton.addEventListener('click', () => {
    console.log('Button clicked via addEventListener!');
  });
</script>

Form Input Events Examples

// OnInput fires on every keystroke

<s-email-field

label="Email"

name="email"

onInput={(e) => console.log('Typing:', e.currentValue.value)}

></s-email-field>

// OnChange fires on blur or Enter press

<s-text-field

label="Name"

name="name"

onChange={(e) => console.log('Value committed:', e.currentValue.value)}

></s-text-field>

// Using both together

<s-email-field

label="Email"

name="email"

onInput={(e) => console.log('Real-time:', e.currentTarget.value)}

onChange={(e) => console.log('Final value:', e.currentTarget.value)}

></s-email-field>

<s-email-field

label="Email"

name="email"

oninput="console.log('Typing:', this.value)"

></s-email-field>

<s-text-field

label="Name"

name="name"

onchange="console.log('Value committed:', this.value)"

></s-text-field>

<s-email-field

label="Email"

name="email"

></s-email-field>

const field = document.querySelector('s-email-field');

field.addEventListener('input', (e) => {

console.log('Real-time:', e.currentTarget.value);

});

field.addEventListener('change', (e) => {

console.log('Final value:', e.currentTarget.value);

});

</script>

JSX

// OnInput fires on every keystroke
<s-email-field
  label="Email"
  name="email"
  onInput={(e) => console.log('Typing:', e.currentValue.value)}
></s-email-field>

// OnChange fires on blur or Enter press
<s-text-field
  label="Name"
  name="name"
  onChange={(e) => console.log('Value committed:', e.currentValue.value)}
></s-text-field>

// Using both together
<s-email-field
  label="Email"
  name="email"
  onInput={(e) => console.log('Real-time:', e.currentTarget.value)}
  onChange={(e) => console.log('Final value:', e.currentTarget.value)}
></s-email-field>

HTML

<s-email-field
  label="Email"
  name="email"
  oninput="console.log('Typing:', this.value)"
></s-email-field>

<s-text-field
  label="Name"
  name="name"
  onchange="console.log('Value committed:', this.value)"
></s-text-field>

<!-- Using addEventListener -->
<s-email-field
  label="Email"
  name="email"
></s-email-field>

<script>
  const field = document.querySelector('s-email-field');

  field.addEventListener('input', (e) => {
    console.log('Real-time:', e.currentTarget.value);
  });

  field.addEventListener('change', (e) => {
    console.log('Final value:', e.currentTarget.value);
  });
</script>

Focus Management Examples

<s-email-field

label="email"

name="email"

onFocus={() => console.log('Field focused')}

onBlur={() => console.log('Field blurred')}

></s-email-field>

<s-text-field

label="Tab to next field to trigger blur"

name="name"

onFocus={(e) => {

e.currentTarget.setAttribute('label', 'Field is active!')

}}

onBlur={(e) => {

e.currentTarget.setAttribute('label', 'Tab to next field to trigger blur')

}}

></s-text-field>

<s-email-field

label="Email"

name="email"

onfocus="console.log('Field focused')"

onblur="console.log('Field blurred')"

></s-email-field>

<s-text-field

label="Tab to next field to trigger blur"

name="name"

></s-text-field>

const field = document.querySelector('s-text-field');

field.addEventListener('focus', () => {

field.setAttribute('label', 'Field is active!');

});

field.addEventListener('blur', () => {

field.setAttribute('label', 'Tab to next field to trigger blur');

});

</script>

JSX

<s-email-field
  label="email"
  name="email"
  onFocus={() => console.log('Field focused')}
  onBlur={() => console.log('Field blurred')}
></s-email-field>

<s-text-field
  label="Tab to next field to trigger blur"
  name="name"
  onFocus={(e) => {
    e.currentTarget.setAttribute('label', 'Field is active!')
  }}
  onBlur={(e) => {
    e.currentTarget.setAttribute('label', 'Tab to next field to trigger blur')
  }}
></s-text-field>

HTML

<s-email-field
  label="Email"
  name="email"
  onfocus="console.log('Field focused')"
  onblur="console.log('Field blurred')"
></s-email-field>

<s-text-field
  label="Tab to next field to trigger blur"
  name="name"
></s-text-field>

<script>
  const field = document.querySelector('s-text-field');

  field.addEventListener('focus', () => {
    field.setAttribute('label', 'Field is active!');
  });

  field.addEventListener('blur', () => {
    field.setAttribute('label', 'Tab to next field to trigger blur');
  });
</script>

Form Values and Types Examples

// Number field example - values are strings

<s-number-field

label="Quantity"

name="quantity"

onChange={(e) => {

// e.currentTarget.value is a string, convert if needed

const quantity = Number(e.currentTarget.value);

console.log('Quantity as number:', quantity);

}}

// Multi-select example - values is an array of strings

<s-choice-list

name="colors"

label="Colors"

multiple

onChange={(e) => {

// e.currentTarget.values is an array of strings

console.log('Selected colors:', e.currentTarget.values);

}}

<s-choice label="Red" value="red" />

<s-choice label="Blue" value="blue" />

<s-choice label="Green" value="green" />

</s-choice-list>

<s-number-field

label="Quantity"

name="quantity"

onchange="console.log('Value type:', typeof this.value, 'Value:', this.value)"

></s-number-field>

<s-choice-list name="colors" label="Colors" multiple>

<s-choice value="red">Red</s-choice>

<s-choice value="blue">Blue</s-choice>

<s-choice value="green">Green</s-choice>

</s-choice-list>

const choiceList = document.querySelector('s-choice-list');

choiceList.addEventListener('change', (e) => {

// e.currentTarget.values is an array of strings

console.log('Selected colors:', e.currentTarget.values);

});

</script>

JSX

// Number field example - values are strings
<s-number-field
  label="Quantity"
  name="quantity"
  onChange={(e) => {
    // e.currentTarget.value is a string, convert if needed
    const quantity = Number(e.currentTarget.value);
    console.log('Quantity as number:', quantity);
  }}
/>

// Multi-select example - values is an array of strings
<s-choice-list
  name="colors"
  label="Colors"
  multiple
  onChange={(e) => {
    // e.currentTarget.values is an array of strings
    console.log('Selected colors:', e.currentTarget.values);
  }}
>
  <s-choice label="Red" value="red" />
  <s-choice label="Blue" value="blue" />
  <s-choice label="Green" value="green" />
</s-choice-list>

HTML

<!-- Number field example - values are strings -->
<s-number-field
  label="Quantity"
  name="quantity"
  onchange="console.log('Value type:', typeof this.value, 'Value:', this.value)"
></s-number-field>

<!-- Multi-select example - values is an array of strings -->
<s-choice-list name="colors" label="Colors" multiple>
  <s-choice value="red">Red</s-choice>
  <s-choice value="blue">Blue</s-choice>
  <s-choice value="green">Green</s-choice>
</s-choice-list>

<script>
  const choiceList = document.querySelector('s-choice-list');

  choiceList.addEventListener('change', (e) => {
    // e.currentTarget.values is an array of strings
    console.log('Selected colors:', e.currentTarget.values);
  });
</script>

Controlled vs. Uncontrolled Components Examples

// Uncontrolled component - internal state

<s-text-field

label="Comment"

name="comment"

defaultValue="Initial value"

onChange={(e) => console.log('New value:', e.currentTarget.value)}

// Controlled component - external state

// In a real component, 'name' would be from framework state

const name = "John Doe";

<s-text-field

label="Name"

name="name"

value={name}

onChange={(e) => {

console.log('Would update state:', e.currentTarget.value)

}}

<s-text-field

label="Comment"

name="comment"

value="Initial value"

onchange="console.log('New value:', this.value)"

></s-text-field>

<s-text-field

id="nameField"

label="Name"

name="name"

value="John Doe"

></s-text-field>

Change Name

</button>

const nameField = document.getElementById('nameField');

// Listen for changes to update our "state"

nameField.addEventListener('input', (e) => {

console.log('Value changed:', e.currentTarget.value);

});

// Manually update the component value (controlled)

function updateName() {

nameField.value = "Jane Smith";

}

</script>

JSX

// Uncontrolled component - internal state
<s-text-field
  label="Comment"
  name="comment"
  defaultValue="Initial value"
  onChange={(e) => console.log('New value:', e.currentTarget.value)}
/>

// Controlled component - external state
// In a real component, 'name' would be from framework state
const name = "John Doe";

<s-text-field
  label="Name"
  name="name"
  value={name}
  onChange={(e) => {
    console.log('Would update state:', e.currentTarget.value)
  }}
/>

HTML

<!-- Uncontrolled component - internal state -->
<s-text-field
  label="Comment"
  name="comment"
  value="Initial value"
  onchange="console.log('New value:', this.value)"
></s-text-field>

<!-- Controlled component - external state -->
<s-text-field
  id="nameField"
  label="Name"
  name="name"
  value="John Doe"
></s-text-field>

<button onclick="updateName()">
  Change Name
</button>

<script>
  const nameField = document.getElementById('nameField');

  // Listen for changes to update our "state"
  nameField.addEventListener('input', (e) => {
    console.log('Value changed:', e.currentTarget.value);
  });

  // Manually update the component value (controlled)
  function updateName() {
    nameField.value = "Jane Smith";
  }
</script>

Complete Examples

<s-button onClick={() => console.log('Clicked!')}>

Click me

</s-button>

<s-email-field

label="Email"

name="email"

onChange={(e) => console.log('Value changed:', e.currentTarget.value)}

onFocus={() => console.log('Field focused')}

onBlur={() => console.log('Field blurred')}

></s-email-field>

<s-button onclick="console.log('Clicked!')">

Click me

</s-button>

<s-text-field

label="Email"

name="email"

onchange="console.log('Value changed:', e.currentTarget.value)"

onfocus="console.log('Field focused')"

onblur="console.log('Field blurred')"

></s-text-field>

const textField = document.querySelector('s-text-field');

textField.addEventListener('change', (e) => {

console.log('Value changed:', e.currentTarget.value);

});

</script>

JSX

<s-button onClick={() => console.log('Clicked!')}>
  Click me
</s-button>

<s-email-field
  label="Email"
  name="email"
  onChange={(e) => console.log('Value changed:', e.currentTarget.value)}
  onFocus={() => console.log('Field focused')}
  onBlur={() => console.log('Field blurred')}
></s-email-field>

HTML

<s-button onclick="console.log('Clicked!')">
  Click me
</s-button>

<s-text-field
  label="Email"
  name="email"
  onchange="console.log('Value changed:', e.currentTarget.value)"
  onfocus="console.log('Field focused')"
  onblur="console.log('Field blurred')"
></s-text-field>

<!-- or -->

<script>
  const textField = document.querySelector('s-text-field');

  textField.addEventListener('change', (e) => {
    console.log('Value changed:', e.currentTarget.value);
  });
</script>

Anchor to SlotsSlots

Slots allow you to insert custom content into specific areas of Polaris web components. Use the slot attribute to specify where your content should appear within a component.

Key points:

Named slots (e.g., slot="title") place content in designated areas
Multiple elements can share the same slot name
Elements without a slot attribute go into the default (unnamed) slot

Anchor to MethodsMethods

Methods are functions available on components for programmatic control. Components like Modal, Sheet, and Announcement provide methods such as hideOverlay() or dismiss() to control their behavior imperatively when needed.

Use methods when you need to trigger actions that can’t be achieved through property changes alone, such as closing an overlay after an async operation or resetting component state.

Example

function Methods() {

const modalRef = useRef(null);

return (

<s-button

command="--show"

commandFor="modal-1"

Open modal

</s-button>

<s-modal

id="modal-1"

ref={modalRef}

heading="Test Modal"

<s-text>Modal content</s-text>

<s-button

onClick={() => {

modalRef.current.hideOverlay();

}}

Close modal

</s-button>

</s-modal>

</>

);

}

function Methods() {

const button =

document.createElement('s-button');

const modal = document.createElement('s-modal');

button.textContent = 'Open Modal';

button.commandFor = 'modal-1';

modal.id = 'modal-1';

modal.heading = 'Test Modal';

const closeButton =

document.createElement('s-button');

closeButton.textContent = 'Close modal';

closeButton.onclick = () => modal.hideOverlay();

modal.appendChild(closeButton);

document.body.appendChild(button);

document.body.appendChild(modal);

}

JSX

function Methods() {
  const modalRef = useRef(null);

  return (
    <>
      <s-button
        command="--show"
        commandFor="modal-1"
      >
        Open modal
      </s-button>
      <s-modal
        id="modal-1"
        ref={modalRef}
        heading="Test Modal"
      >
        <s-text>Modal content</s-text>
        <s-button
          onClick={() => {
            modalRef.current.hideOverlay();
          }}
        >
          Close modal
        </s-button>
      </s-modal>
    </>
  );
}

JS

function Methods() {
  const button =
    document.createElement('s-button');
  const modal = document.createElement('s-modal');

  button.textContent = 'Open Modal';
  button.commandFor = 'modal-1';

  modal.id = 'modal-1';
  modal.heading = 'Test Modal';

  const closeButton =
    document.createElement('s-button');

  closeButton.textContent = 'Close modal';
  closeButton.onclick = () => modal.hideOverlay();

  modal.appendChild(closeButton);

  document.body.appendChild(button);
  document.body.appendChild(modal);
}

Anchor to Using FormsUsing Forms

The Form component provides a way to manage form state and submit data to your app’s backend or directly to Shopify using Direct API access. When the form is submitted or reset the relevant callback in the form component will get triggered.

Using this, you can control what defines a component to be dirty by utilizing the input’s defaultValue property.

Rules:

When the defaultValue is set, the component will be considered dirty if the value of the input is different from the defaultValue. You may update the defaultValue when the form is submitted to reset the dirty state of the form.
When the defaultValue is not set, the component will be considered dirty if the value of the input is different from the initial value or from the last dynamic update to the input’s value that wasn’t triggered by user input.

Note: In order to trigger the dirty state, each input must have a name attribute.

Trigger the Form’s dirty state

import { render } from 'preact';

import { useState } from 'preact/hooks';

export default function extension() {

render(<Extension />, document.body);

}

const defaultValues = {

text: 'default value',

number: 50,

};

function Extension() {

const [textValue, setTextValue] = useState('');

const [numberValue, setNumberValue] = useState('');

return (

<s-form onSubmit={() => console.log('submit', {textValue, numberValue})}>

<s-stack gap="base">

<s-text-field

label="Default Value"

name="my-text"

defaultValue={defaultValues.text}

value={textValue}

onChange={(e) => setTextValue(e.target.value)}

<s-number-field

label="Percentage field"

name="my-number"

defaultValue={defaultValues.number}

value={numberValue}

onChange={(e) => setNumberValue(e.target.value)}

</s-stack>

</s-form>

);

}

import { render } from 'preact';

import { useState } from 'preact/hooks';

export default function extension() {

render(<Extension />, document.body);

}

async function Extension() {

const data = await fetch('/data.json');

const {text, number} = await data.json();

return <App text={text} number={number} />;

}

function App({text, number}) {

// The initial values set in the form fields will be the default values

const [textValue, setTextValue] = useState(text);

const [numberValue, setNumberValue] = useState(number);

return (

<s-form onSubmit={() => console.log('submit', {textValue, numberValue})}>

<s-stack gap="base">

<s-text-field

label="Default Value"

name="my-text"

value={textValue}

onChange={(e) => setTextValue(e.target.value)}

<s-number-field

label="Percentage field"

name="my-number"

value={numberValue}

onChange={(e) => setNumberValue(e.target.value)}

</s-stack>

</s-form>

);

}

Using `defaultValue`

import { render } from 'preact';
import { useState } from 'preact/hooks';

export default function extension() {
  render(<Extension />, document.body);
}

const defaultValues = {
  text: 'default value',
  number: 50,
};

function Extension() {
  const [textValue, setTextValue] = useState('');
  const [numberValue, setNumberValue] = useState('');

  return (
      <s-form onSubmit={() => console.log('submit', {textValue, numberValue})}>
        <s-stack gap="base">
          <s-text-field
            label="Default Value"
            name="my-text"
            defaultValue={defaultValues.text}
            value={textValue}
            onChange={(e) => setTextValue(e.target.value)}
          />
          <s-number-field
            label="Percentage field"
            name="my-number"
            defaultValue={defaultValues.number}
            value={numberValue}
            onChange={(e) => setNumberValue(e.target.value)}
          />
        </s-stack>
      </s-form>
  );
}

Using implicit default

import { render } from 'preact';
import { useState } from 'preact/hooks';

export default function extension() {
  render(<Extension />, document.body);
}

async function Extension() {
  const data = await fetch('/data.json');
  const {text, number} = await data.json();
  return <App text={text} number={number} />;
}

function App({text, number}) {
  // The initial values set in the form fields will be the default values
  const [textValue, setTextValue] = useState(text);
  const [numberValue, setNumberValue] = useState(number);

  return (
      <s-form onSubmit={() => console.log('submit', {textValue, numberValue})}>
        <s-stack gap="base">
          <s-text-field
            label="Default Value"
            name="my-text"
            value={textValue}
            onChange={(e) => setTextValue(e.target.value)}
          />
          <s-number-field
            label="Percentage field"
            name="my-number"
            value={numberValue}
            onChange={(e) => setNumberValue(e.target.value)}
          />
        </s-stack>
      </s-form>
  );
}

Anchor to AccessibilityAccessibility

Polaris web components are built with accessibility in mind. They:

Use semantic HTML under the hood
Support keyboard navigation
Include proper ARIA attributes
Manage focus appropriately
Provide appropriate color contrast
Log warnings when component properties are missing and required for accessibility

To ensure your application remains accessible, follow these best practices:

Always use the label and error properties for form elements
Use appropriate heading levels with s-heading or the heading property
Ensure sufficient color contrast
Test keyboard navigation
Use labelAccessibilityVisibility to hide labels and keep them visible to assistive technologies
Use accessibilityRole to specify the aria-role of the component

Anchor to TroubleshootingTroubleshooting

Common issues and debugging tips for using Polaris web components.

Common issues

Properties not updating: Ensure you’re using the property name as documented, not a different casing or naming convention.
Event handlers not firing: Check that you’re using the correct event name (e.g., onClick for click events).
Form values not being submitted: Make sure your form elements have name attributes.

Debugging tips

Inspect the element in your browser’s developer tools to see the current property and attribute values.
Use console.log to verify that event handlers are being called and receiving the expected event objects.
Check for any errors in the browser console that might indicate issues with your component usage.

Was this page helpful?