### Checkout UI Extension Configuration Example

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/configuration

Example TOML file demonstrating configuration settings for a checkout UI extension.

```toml
# Example TOML file for a checkout UI extension

[settings.shipping_address.fields.first_name]
type = "single_line_text_field"
label = "First name"

[settings.shipping_address.fields.last_name]
type = "single_line_text_field"
label = "Last name"

[settings.shipping_address.fields.phone]
type = "single_line_text_field"
label = "Phone number"
validation = {
  name = "regex"
  value = "^\\+?[1-9]\\d{1,14}$"
}

[settings.shipping_address.fields.country]
type = "single_line_text_field"
label = "Country"
validation = {
  name = "choices"
  value = '["USA", "Canada", "Mexico"]'
}

[settings.shipping_address.fields.zip_code]
type = "single_line_text_field"
label = "ZIP code"
validation = {
  name = "min"
  value = "5"
}

[settings.shipping_address.fields.notes]
type = "multi_line_text_field"
label = "Notes"
validation = {
  name = "max"
  value = "500"
}

[settings.delivery_date]
type = "date"
label = "Delivery date"
validation = {
  name = "min"
  value = "2023-01-01"
}

[settings.delivery_time]
type = "date_time"
label = "Delivery time"
validation = {
  name = "min"
  value = "2023-01-01T09:00:00"
}

[settings.quantity]
type = "number_integer"
label = "Quantity"
validation = {
  name = "min"
  value = "1"
}

[settings.discount]
type = "number_decimal"
label = "Discount"
validation = {
  name = "max_precision"
  value = "2"
}

```

--------------------------------

### Stack Component Example

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/layout-and-structure/stack

Demonstrates basic usage of the Stack component for vertical arrangement of elements with spacing.

```javascript
import { Stack, Text } from '@shopify/ui-extensions/customer-account';

export default function MyComponent() {
  return (
    <Stack spacing="base">
      <Text>First item</Text>
      <Text>Second item</Text>
      <Text>Third item</Text>
    </Stack>
  );
}
```

--------------------------------

### Chip with Icon Example

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/actions/clickable-chip

Adds a graphic, such as an icon, to the start of the chip to visually reinforce its label. Use the `graphic` slot for this purpose.

```html
<s-clickable-chip>
  <s-icon type="discount" slot="graphic"></s-icon>
  On sale
</s-clickable-chip>
```

--------------------------------

### Basic Tooltip Usage

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/overlays/tooltip

Demonstrates how to use tooltips with clickable elements to provide additional context. This example shows tooltips for tracking and help icons.

```html
<s-stack direction="inline" gap="small-400">
<s-clickable interestFor="track-tooltip">
<s-icon type="delivery" />
</s-clickable>
<s-clickable interestFor="help-tooltip">
<s-icon type="info" />
</s-clickable>
</s-stack>
<s-tooltip id="track-tooltip">Track your order</s-tooltip>
<s-tooltip id="help-tooltip">Get help with this order</s-tooltip>
```

--------------------------------

### Stack with Wrap

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/layout-and-structure/stack

Example of enabling wrapping for Stack items when they exceed available space.

```javascript
import { Stack, Text } from '@shopify/ui-extensions/customer-account';

export default function MyComponent() {
  return (
    <Stack spacing="base" wrap>
      <Text>Item 1</Text>
      <Text>Item 2</Text>
      <Text>Item 3</Text>
      <Text>Item 4</Text>
      <Text>Item 5</Text>
    </Stack>
  );
}
```

--------------------------------

### Select with placeholder text

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/forms/select

Shows a dropdown with hint text to prompt the customer for a selection. This example uses a placeholder for language selection.

```html
<s-select label="Preferred language" placeholder="Choose a language">
  <s-option value="en">English</s-option>
  <s-option value="fr">French</s-option>
  <s-option value="es">Spanish</s-option>
  <s-option value="de">German</s-option>
</s-select>
```

--------------------------------

### Collect a website URL

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/forms/url-field

Add a URL input with a pre-filled value. This example shows a URL field with a label and value.

```html
<s-url-field
  label="Website"
  value="https://shopify.com"
></s-url-field>
```

--------------------------------

### Display a QR code

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/media-and-visuals/qr-code

Render a scannable QR code from a URL. This example encodes a link that customers can scan with their smartphone to visit the destination.

```html
<s-qr-code content="https://shopify.dev" accessibilityLabel="Scan to visit Shopify.dev"></s-qr-code>
```

--------------------------------

### Display a labeled loading state

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/feedback-and-status-indicators/spinner

Pair a spinner with text to describe what's loading. This example centers a spinner above a descriptive message.

```html
<s-stack direction="block" gap="small-200" align-items="center">
<s-spinner accessibility-label="Loading order details"></s-spinner>
<s-text color="subdued">Loading order details...</s-text>
</s-stack>
```

--------------------------------

### Basic section with content

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/layout-and-structure/section

Use a section to wrap related content under a descriptive heading. This example shows a rewards section with descriptive text and action buttons.

```html
<s-section heading="Rewards">
  <s-stack direction="block" gap="base">
    <s-text>Earn 10 points for every $1 spent. Redeem 100 points for $10 off your next purchase</s-text>
    <s-stack direction="inline" gap="base">
      <s-button variant="primary">Redeem</s-button>
      <s-button variant="secondary">My rewards</s-button>
    </s-stack>
  </s-stack>
</s-section>
```

--------------------------------

### Create a Collapsible Section

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/typography-and-content/details

Use s-details and s-summary to hide supplementary content until the customer chooses to expand it. This example wraps pickup instructions.

```html
<s-details>
  <s-summary>Pickup instructions</s-summary>
  <s-text>
    Curbside pickup is at the back of the warehouse. Park in a stall and follow the signs.
  </s-text>
</s-details>
```

--------------------------------

### Confirming Destructive Actions

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/overlays/modal

This example demonstrates how to use a modal to confirm a destructive action, such as canceling a subscription. It pairs a cancel button with a critical-toned action button.

```html
<s-button command="--show" commandFor="delete-modal">Cancel subscription</s-button>
<s-modal id="delete-modal" heading="Cancel subscription?">
<s-paragraph>
This will cancel your subscription immediately. You'll lose access to
all benefits at the end of your current billing period.
</s-paragraph>
<s-button
command="--hide"
commandFor="delete-modal"
slot="secondary-actions"
>
Keep subscription
</s-button>
<s-button
variant="primary"
tone="critical"
command="--hide"
commandFor="delete-modal"
slot="primary-action"
>
Cancel subscription
</s-button>
</s-modal>
```

--------------------------------

### Using Icons in Badges

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/media-and-visuals/icon

Shows how to associate icons with badge components to visually represent status. This example includes neutral and critical badges with corresponding icons.

```html
<s-stack direction="inline" gap="base">
<s-badge tone="neutral" icon="check-circle">Delivered</s-badge>
<s-badge tone="critical" icon="alert-triangle">Action needed</s-badge>
</s-stack>
```

--------------------------------

### Initiate Return with Login Check

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/account-apis/require-login-api

This example shows how to initiate a return after ensuring the buyer is logged in. It first checks the authentication state and only calls `shopify.requireLogin()` if the buyer is not yet fully authenticated.

```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useState} from 'preact/hooks';

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

function Extension() {
  const [submitted, setSubmitted] =
    useState(false);

  async function initiateReturn() {
    await shopify.requireLogin();

    const authState =
      shopify.authenticationState.value;
    if (authState !== 'fully_authenticated') {
      return;
    }

    setSubmitted(true);
  }

  if (submitted) {
    return (
      <s-banner tone="success">
        Your return request has been submitted.
        We will send a confirmation email shortly.
      </s-banner>
    );
  }

  return (
    <s-box padding="base">
      <s-stack direction="block" gap="small-200">
        <s-text type="strong">
          Need to return an item?
        </s-text>
        <s-text>
          You will be asked to log in before
          submitting a return request.
        </s-text>
        <s-button onClick={initiateReturn}>
          Start a return
        </s-button>
      </s-stack>
    </s-box>
  );
}
```

--------------------------------

### Deep-link to Another Extension

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/platform-apis/navigation-api

Deep-links to a different installed extension using the 'extension://<handle>' protocol. This example navigates to a loyalty rewards extension.

```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

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

function Extension() {
  function handleNavigate() {
    shopify.navigation.navigate(
      'extension://loyalty-rewards',
    );
  }

  return (
    <s-banner heading="Loyalty program">
      <s-text>
        You have 1,200 points available.
      </s-text>
      <s-button onClick={handleNavigate}>
        View rewards
      </s-button>
    </s-banner>
  );
}
```

--------------------------------

### Programmatically Hide a Toast

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/platform-apis/toast-api

This example shows how to get a handle to a toast notification and dismiss it programmatically using the `hide()` method. This is useful for custom dismissal logic.

```javascript
import { showToast } from '@shopify/customer-account-ui-extensions/toast';

const toastHandle = await showToast('Processing your request...');

// To dismiss the toast programmatically:
// toastHandle.hide();
```

--------------------------------

### Use responsive images

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/media-and-visuals/image

Set up responsive image sources using `srcSet` and `sizes`. This example configures the browser to select appropriate image sources based on viewport width.

```html
<s-image
  src="https://cdn.shopify.com/static/images/polaris/thumbnail-wc_src.jpg"
  srcSet="https://cdn.shopify.com/static/images/polaris/thumbnail-wc_src.jpg 400w,
https://cdn.shopify.com/static/images/polaris/thumbnail-wc_src.jpg 800w"
  sizes="(max-width: 600px) 100vw, (max-width: 1200px) 50vw, 400px"
  alt="White sneakers"
  aspectRatio="1/1"
  inlineSize="fill"
  objectFit="cover"
></s-image>
```

--------------------------------

### Show Range Validation Error

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/forms/number-field

Display an error message when the input value exceeds the allowed range. This example configures a number field with `min`, `max`, and an `error` message to guide the user.

```html
<s-number-field label="Quantity" min="1" max="10" step="1" defaultValue="1" error="Maximum 10 items per order"></s-number-field>
```

--------------------------------

### Navigate to an Extension Route

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/platform-apis/navigation-api

This example demonstrates how to navigate to a specific route within the current extension using the `extension://` protocol. It renders a button that, when clicked, triggers navigation to the 'orders' path.

```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';
  
export default async () => {
render(<Extension />, document.body);
};
  
function Extension() {
return (
<s-button
onClick={() => {
shopify.navigation.navigate('extension://orders');
}}
>
Navigate to orders path
</s-button>
);
}
```

--------------------------------

### Get customer's country and display region-specific message

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/platform-apis/localization-api

Read the customer's country to conditionally render region-specific messaging. This example checks if the customer is in Canada and displays a warning if so. Guard against missing localization data as these values load asynchronously.

```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

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

function Extension() {
  const countryCode =
    shopify.localization?.country?.value?.isoCode;

  if (countryCode === 'CA') {
    return (
      <s-banner status="warning">
        {shopify.i18n.translate(
          'canadaPostWarningMessage',
        )}
      </s-banner>
    );
  }
}
```

```json
{
  "canadaPostWarningMessage": "Canada Post has issued a red delivery service alert for Ontario due to a severe snowstorm, suspending package delivery and collection for the week."
}
```

--------------------------------

### Display Related Products in Order Status Extension

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/targets/order-status

This example fetches product recommendations from your app's backend using the session token for authentication and displays them as a list below the line item list. It requires a backend endpoint at 'https://your-app.com/api/recommendations' to provide product data.

```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useState, useEffect} from 'preact/hooks';
  
export default async () => {
  render(<Extension />, document.body);
};
  
function Extension() {
  const [recommendations, setRecommendations] = useState(null);
  
  useEffect(() => {
    async function fetchRecommendations() {
      const token = await shopify.sessionToken.get();
      const res = await fetch('https://your-app.com/api/recommendations', {
        headers: {Authorization: `Bearer ${token}`},
      });
      const data = await res.json();
      setRecommendations(data.products);
    }
    fetchRecommendations();
  }, []);
  
  if (!recommendations || recommendations.length === 0) return null;
  
  return (
    <s-section heading="You might also like">
      <s-stack direction="block" gap="base">
        {recommendations.map((product) => (
          <s-stack key={product.id} direction="inline" gap="base">
            <s-text type="strong">{product.title}</s-text>
            <s-link href={product.url}>View product</s-link>
          </s-stack>
        ))}
      </s-stack>
    </s-section>
  );
}
```

--------------------------------

### Link to the storefront

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/order-apis/shop-api

Create a link back to the merchant's online store from your extension. This example reads `shopify.shop.storefrontUrl` and renders a "Continue Shopping" button that navigates to the storefront.

```APIDOC
## Link to the storefront

### Description
This example demonstrates how to create a link back to the merchant's online store using the `storefrontUrl` property of the `shopify.shop` object. It renders a "Continue Shopping" button that navigates the user to the storefront.

### Code Example (JSX)
```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

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

function Extension() {
  const shop = shopify.shop;

  return (
    <s-box padding="base" border="base" borderRadius="base">
      <s-stack direction="block" gap="small-200">
        <s-text type="strong">Continue Shopping</s-text>
        <s-text color="subdued">
          Browse more products from {shop.name}.
        </s-text>
        <s-button href={shop.storefrontUrl}>Visit {shop.name}</s-button>
      </s-stack>
    </s-box>
  );
}
```
```

--------------------------------

### Stack: Align items to the start

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/layout-and-structure/stack

Use `alignment="start"` to align items to the beginning of the stack's cross axis. This is the default behavior.

```javascript
import {
  Stack, 
  Text
} from "@shopify/polaris-react-ui";

function MyComponent() {
  return (
    <Stack alignment="start">
      <Text>First Item</Text>
      <Text>Second Item</Text>
    </Stack>
  );
}
```

--------------------------------

### Query Products with shopify.query Helper

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/platform-apis/storefront-api

Use the `shopify.query()` helper to run a Storefront GraphQL query with variables. This example fetches the first five products and renders their titles in a list. Requires the `api_access` capability.

```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useEffect, useState} from 'preact/hooks';
  
export default async () => {
render(<Extension />, document.body);
};
  
function Extension() {
const [data, setData] = useState({});
  
useEffect(() => {
shopify
.query(
`query ($first: Int!) {
products(first: $first) {
nodes {
id
title
}
}
}`,
{
variables: {first: 5},
},
)
.then(({data, errors}) => {
setData(data);
})
.catch(console.error);
}, [setData]);
  
return (
<s-unordered-list>
{data?.products?.nodes.map((node) => {
return (
<s-list-item id={node.id} key={node.id}>
{node.title}
</s-list-item>
);
})}
</s-unordered-list>
);
}
```

--------------------------------

### Fetch Product Details using shopify.query()

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/platform-apis/storefront-api

This snippet demonstrates how to query for a specific product's title and description using the `shopify.query()` helper. It includes basic loading and error handling.

```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useEffect, useState} from 'preact/hooks';

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

function Extension() {
  const [data, setData] = useState<any>(null);

  useEffect(() => {
    shopify
      .query(
        `query ($id: ID!) {
        product(id: $id) {
          title
          description
        }
      }`,
        {
          variables: {
            id: 'gid://shopify/Product/1',
          },
        },
      )
      .then(({data}) => {
        setData(data);
      })
      .catch(console.error);
  }, []);

  if (!data?.product) {
    return <s-spinner />;
  }

  return (
    <s-stack direction="block" gap="base">
      <s-heading>
        {data.product.title}
      </s-heading>
      <s-text>
        {data.product.description}
      </s-text>
    </s-stack>
  );
}
```

--------------------------------

### MatchedSubstring Type

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/platform-apis/extension-api

Represents a matched substring within text, including its length and starting offset.

```typescript
number
```

```typescript
number
```

--------------------------------

### Create a Two-Column Summary with Flexible Widths

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/layout-and-structure/grid

Use `gridTemplateColumns="1fr auto"` to create a two-column layout where the first column takes up available space and the second column fits its content. This is useful for pairing labels with values, like product names and prices.

```html
<s-grid gridTemplateColumns="1fr auto" gap="small-200">
<s-text>Plants for sale</s-text>
<s-text></s-text>
<s-text>Pothos</s-text>
<s-text>$25.00</s-text>
</s-grid>
```

--------------------------------

### Removable Chip Example

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/actions/clickable-chip

Displays a chip that can be dismissed by the user. Use the `removable` attribute to enable this functionality.

```html
<s-clickable-chip removable>Shipping insurance</s-clickable-chip>
```

--------------------------------

### Query products with the query helper

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/platform-apis/storefront-api

Use the `shopify.query()` helper to run a Storefront GraphQL query with variables. This example fetches the first five products and renders their titles in a list.

```APIDOC
## shopify.query()

### Description
Queries the Storefront GraphQL API directly from your extension using a prefetched token. Use this to fetch product data, collection details, or other storefront information without routing requests through your app backend.

### Method
```javascript
query<Data = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: StorefrontApiVersion; }): Promise<{ data?: Data; errors?: GraphQLError[]; }>
```

### Parameters
#### Query Parameters
- **query** (string) - Required - The GraphQL query string.
- **options** (object) - Optional - An object containing query options.
  - **variables** (object) - Optional - An object containing variables for the GraphQL query.
  - **version** (StorefrontApiVersion) - Optional - The Storefront API version to target.

### Request Example
```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useEffect, useState} from 'preact/hooks';

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

function Extension() {
  const [data, setData] = useState({});

  useEffect(() => {
    shopify
      .query(
        `query ($first: Int!) {
        products(first: $first) {
          nodes {
            id
            title
          }
        }
      }`,
        {
          variables: {first: 5},
        },
      )
      .then(({data, errors}) => {
        setData(data);
      })
      .catch(console.error);
  }, [setData]);

  return (
    <s-unordered-list>
      {data?.products?.nodes.map((node) => (
        <s-list-item id={node.id} key={node.id}>
          {node.title}
        </s-list-item>
      ))}
    </s-unordered-list>
  );
}
```

### Response
#### Success Response
- **data** (object) - The data returned from the GraphQL query.
- **errors** (array) - An array of `GraphQLError` objects if the query failed.

### StorefrontApiVersion
The supported Storefront API versions.
```
'2022-04' | '2022-07' | '2022-10' | '2023-01' | '2023-04' | '2023-07' | '2024-01' | '2024-04' | '2024-07' | '2024-10' | '2025-01' | '2025-04' | 'unstable' | '2025-07' | '2025-10'
```

### GraphQLError
An error returned by the Storefront GraphQL API.
  * **extensions** (object) - Additional error metadata including the request ID and error code.
    * **requestId** (string)
    * **code** (string)
  * **message** (string) - A human-readable description of the error.
```

--------------------------------

### Submit Return Request in a Full-Page Extension

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/targets/full-page

This example shows a full-page extension for submitting return requests. It displays order items and allows users to select items for return, then submits the request. It utilizes `shopify.lines.value` to list order items.

```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useState} from 'preact/hooks';

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

function Extension() {
  const order = shopify.order.value;
  const lines = shopify.lines.value;
  const [submitted, setSubmitted] = useState(false);

  if (!order) {
    return null;
  }

  if (submitted) {
    return (
      <s-page heading="Return Request Submitted" subheading={`Order ${order.name}`}> 
        <s-button
          slot="primary-action"
          onClick={() => navigation.navigate('shopify:customer-account/orders')}
        >
          Back to orders
        </s-button>
        <s-banner tone="success">
          Your return request has been submitted. We'll review it and get back to you.
        </s-banner>
      </s-page>
    );
  }

  return (
    <s-page heading="Request a Return" subheading={`Order ${order.name}`}> 
      <s-button
        slot="primary-action"
        onClick={() => navigation.navigate('shopify:customer-account/orders')}
      >
        Back to orders
      </s-button>
      <s-stack direction="block" gap="base">
        <s-text>Select items to return from order {order.name}:</s-text>
        <s-stack direction="block" gap="base">
          {lines.map((line) => (
            <s-stack key={line.id} direction="inline" gap="base" alignItems="center">
              <s-text>{line.merchandise.title}</s-text>
              <s-text color="subdued">Qty: {line.quantity}</s-text>
            </s-stack>
          ))}
        </s-stack>
        <s-button onClick={() => setSubmitted(true)}>
          Submit return request
        </s-button>
      </s-stack>
    </s-page>
  );
}
```

--------------------------------

### Extension Editor Context

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/platform-apis/extension-api

Get information about the editor environment where the extension is being rendered. Returns undefined if not in an editor.

```typescript
Editor
```

--------------------------------

### Link to Storefront using Shop API

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/order-apis/shop-api

Create a link back to the merchant's online store from your extension. This example reads shop.storefrontUrl and renders a button that navigates to the storefront.

```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

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

function Extension() {
  const shop = shopify.shop;

  return (
    <s-box padding="base" border="base" borderRadius="base">
      <s-stack direction="block" gap="small-200">
        <s-text type="strong">Continue Shopping</s-text>
        <s-text color="subdued">
          Browse more products from {shop.name}.
        </s-text>
        <s-button href={shop.storefrontUrl}>Visit {shop.name}</s-button>
      </s-stack>
    </s-box>
  );
}
```

--------------------------------

### Collect a password

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/forms/password-field

Add a password input that masks characters for privacy. This example shows a password field with a label and a defaultValue.

```html
<s-password-field
label="Password"
defaultValue="12345678"
></s-password-field>
```

--------------------------------

### Footer Target Example

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/targets

This target renders at the bottom of all customer account pages. Use it for global announcements or legal compliance.

```plaintext
customer-account.footer.render-after
```

--------------------------------

### Display Order Preparation Notice

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/targets/fulfillment-status

Show a banner informing customers that their items are being prepared for shipment. This example reads order data from `shopify.order` to include the order name for context. Always check that `shopify.order.value` is defined before rendering order-specific content.

```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

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

function Extension() {
  const order = shopify.order.value;

  if (!order) {
    return null;
  }

  return (
    <s-banner tone="info">
      Items from order {order.name} are being prepared. You'll receive tracking
      details once they ship.
    </s-banner>
  );
}
```

--------------------------------

### Display an order cost summary

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/order-apis/cost-api

This example demonstrates how to render an order cost summary by accessing and displaying the subtotal, shipping, tax, and total amounts. It formats each amount with its corresponding currency code.

```APIDOC
## jsx

```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';
  
export default async () => {
  render(<Extension />, document.body);
};
  
function Extension() {
  const subtotal = shopify.cost.subtotalAmount.value;
  const shipping = shopify.cost.totalShippingAmount.value;
  const tax = shopify.cost.totalTaxAmount.value;
  const total = shopify.cost.totalAmount.value;
  
  return (
    <s-box>
      <s-stack>
        <s-stack direction="inline">
          <s-text>Subtotal</s-text>
          <s-text>
            {subtotal.amount} 
            {subtotal.currencyCode}
          </s-text>
        </s-stack>
        {shipping && (
          <s-stack direction="inline">
            <s-text>Shipping</s-text>
            <s-text>
              {shipping.amount} 
              {shipping.currencyCode}
            </s-text>
          </s-stack>
        )}
        {tax && (
          <s-stack direction="inline">
            <s-text>Tax</s-text>
            <s-text>
              {tax.amount} 
              {tax.currencyCode}
            </s-text>
          </s-stack>
        )}
        <s-stack direction="inline">
          <s-text>Total</s-text>
          <s-text>
            {total.amount} 
            {total.currencyCode}
          </s-text>
        </s-stack>
      </s-stack>
    </s-box>
  );
}
```
```

--------------------------------

### Inline Stack with Images

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/layout-and-structure/stack

Use an inline stack to arrange elements horizontally. This example displays multiple product images side-by-side.

```html
<s-stack direction="inline" gap="base" alignItems="center">
<s-image src="https://cdn.shopify.com/s/files/1/0533/2089/files/placeholder-images-product-1.png" inlineSize="80px" blockSize="80px" objectFit="cover" borderRadius="base"></s-image>
<s-image src="https://cdn.shopify.com/s/files/1/0533/2089/files/placeholder-images-product-2.png" inlineSize="80px" blockSize="80px" objectFit="cover" borderRadius="base"></s-image>
<s-image src="https://cdn.shopify.com/s/files/1/0533/2089/files/placeholder-images-product-3.png" inlineSize="80px" blockSize="80px" objectFit="cover" borderRadius="base"></s-image>
<s-image src="https://cdn.shopify.com/s/files/1/0533/2089/files/placeholder-images-product-4.png" inlineSize="80px" blockSize="80px" objectFit="cover" borderRadius="base"></s-image>
</s-stack>
```

--------------------------------

### Show a disabled field

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/forms/url-field

Show a URL in a non-interactive state. This example uses disabled to gray out the field while keeping the value visible.

```html
<s-url-field
  label="Store URL"
  value="https://your-store.myshopify.com"
  disabled
></s-url-field>
```

--------------------------------

### Menu with Sections and Navigation

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/actions/menu

Organizes menu items into labeled sections using `s-section` components. This example demonstrates how to separate help resources from support options within a menu, with links opening in new tabs.

```html
<s-button commandFor="help-menu">
  Help
</s-button>


<s-menu id="help-menu" accessibilityLabel="Help options">
  <s-section heading="Resources">
    <s-button href="https://help.shopify.com" target="_blank">Visit help center</s-button>
    <s-button href="https://community.shopify.com" target="_blank">Community forums</s-button>
  </s-section>
  <s-section heading="Support">
    <s-button>Contact support</s-button>
  </s-section>
</s-menu>
```

--------------------------------

### Limit Character Count

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/forms/text-area

Restrict input length and display the remaining character count. This example sets a maxLength of 200 characters.

```html
<s-text-area
  label="Gift message"
  maxLength={200}
  rows={4}
></s-text-area>
```

--------------------------------

### Calculate and Display Total Savings

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/order-apis/discounts-api

Calculates and displays the total savings from all discount allocations. This example iterates over `shopify.discountAllocations` to sum the discounted amounts and shows a per-discount breakdown. It requires discount allocations to be present.

```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

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

function Extension() {
  const allocations =
    shopify.discountAllocations.value;

  if (allocations.length === 0) {
    return null;
  }

  const totalSavings = allocations.reduce(
    (sum, allocation) =>
      sum +
      Number(allocation.discountedAmount.amount),
    0,
  );

  const currencyCode =
    allocations[0].discountedAmount.currencyCode;

  return (
    <s-box>
      <s-text type="strong">
        You saved {totalSavings.toFixed(2)} 
        {currencyCode}
      </s-text>
      <s-divider />
      {allocations.map((allocation, index) => (
        <s-text key={index}>
          -{allocation.discountedAmount.amount} 
          {
            allocation.discountedAmount
              .currencyCode
          }
        </s-text>
      ))}
    </s-box>
  );
}
```

--------------------------------

### Provide a text alternative

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/media-and-visuals/qr-code

Pair the QR code with a text link so all customers can access the content. This example adds a paragraph with a clickable link below the code for customers who can't scan.

```html
<s-stack gap="base">
<s-qr-code
content="https://shopify.com/returns/abc123"
accessibilityLabel="Scan for return label"
></s-qr-code>
<s-paragraph>
Scan to access your return label, or visit
<s-link href="https://shopify.com/returns/abc123">shopify.com/returns/abc123</s-link>
</s-paragraph>
</s-stack>
```

--------------------------------

### Grouped Switches for Preferences

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/forms/switch

Organize related preferences using a stack layout with multiple switches. This example shows notification preferences.

```html
<s-stack gap="base">
<s-switch label="Email notifications"></s-switch>
<s-switch label="SMS notifications"></s-switch>
<s-switch label="Push notifications" checked></s-switch>
</s-stack>
```

--------------------------------

### Query Storefront API with fetch

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/platform-apis/storefront-api

Use the global `fetch()` function to query the GraphQL Storefront API directly. This example fetches products using a POST request and renders the results. Requires the `api_access` capability.

```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useEffect, useState} from 'preact/hooks';

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

function Extension() {
  const [data, setData] = useState();

  useEffect(() => {
    const getProductsQuery = {
      query: `query ($first: Int!) {
        products(first: $first) {
          nodes {
            id
            title
          }
        }
      }`,
      variables: {first: 5},
    };

    const apiVersion = 'unstable';

    fetch(
      `shopify://storefront/api/${apiVersion}/graphql.json`,
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(getProductsQuery),
      },
    )
      .then((response) => response.json())
      .then(({data, errors}) => setData(data))
      .catch(console.error);
  }, []);

  return (
    <s-unordered-list>
      {data?.products?.nodes.map((node) => (
        <s-list-item key={node.id}>
          {node.title}
        </s-list-item>
      ))}
    </s-unordered-list>
  );
}
```

--------------------------------

### Extension Target Identifier

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/platform-apis/extension-api

Get the identifier specifying where the code is injected into Shopify's UI, as defined in the extension's configuration.

```typescript
Target
```

--------------------------------

### Prompting Login for Pre-Authenticated Buyers

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/account-apis/authentication-state-api

Detect pre-authenticated buyers and encourage them to log in for a richer experience. This example checks `shopify.authenticationState` and displays a login prompt with a button that calls `shopify.requireLogin()`.

```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

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

function Extension() {
  const authState =
    shopify.authenticationState.value;

  if (authState === 'pre_authenticated') {
    return (
      <s-banner tone="warning">
        <s-stack direction="block" gap="small-200">
          <s-text>
            You are viewing a limited version of
            this page. Sign in to see full order
            details and manage your account.
          </s-text>
          <s-button
            onClick={() => shopify.requireLogin()}
          >
            Sign in
          </s-button>
        </s-stack>
      </s-banner>
    );
  }

  return (
    <s-text color="subdued">
      You are fully authenticated.
    </s-text>
  );
}
```

--------------------------------

### Use in a grid layout

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/media-and-visuals/image

Arrange product photos in a row, each constrained to a square with rounded corners so they line up evenly. This example arranges three product photos in a row using a grid.

```html
<s-grid gridTemplateColumns="repeat(3, 150px)" gap="base" alignItems="center">
<s-image
  src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
  alt="Indoor plant in a gray pot"
  aspectRatio="1/1"
  objectFit="cover"
  borderRadius="base"
  inlineSize="fill"
></s-image>
<s-image
  src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
  alt="Indoor plant in a gray pot"
  aspectRatio="1/1"
  objectFit="cover"
  borderRadius="base"
  inlineSize="fill"
></s-image>
<s-image
  src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
  alt="Indoor plant in a gray pot"
  aspectRatio="1/1"
  objectFit="cover"
  borderRadius="base"
  inlineSize="fill"
></s-image>
</s-grid>
```

--------------------------------

### Add border styling

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/media-and-visuals/image

Add visual emphasis with border styling. This example displays an image with border width, color, and rounded corners.

```html
<s-box inlineSize="300px">
<s-image
  src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
  alt="Indoor plant in a gray pot"
  borderWidth="large"
  borderRadius="large"
  objectFit="cover"
  aspectRatio="1/1"
  inlineSize="fill"
></s-image>
</s-box>
```

--------------------------------

### Display a Basic Product Thumbnail

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/media-and-visuals/product-thumbnail

Use this snippet to show a standard product thumbnail with an image source and alt text for accessibility.

```html
<s-product-thumbnail
alt="Indoor plant in a gray pot"
src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
></s-product-thumbnail>
```

--------------------------------

### Example shopify.extension.toml for Checkout UI Extension

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/configuration

This TOML file configures a checkout UI extension, including API version, extension details, capabilities, targeting information, and settings fields.

```toml
api_version = "2025-10"

[[extensions]]
name = "My UI extension"
description = "A UI extension"
handle = "my-ui-extension"
type = "ui_extension"
uid = "1aafc25d-8448-218e-9373-b3d91ac2a0af75f73e12"

[extensions.capabilities]
api_access = true
block_progress = true
network_access = true

[[extensions.targeting]]
module = "./src/CheckoutDynamicRender.js"
target = "purchase.checkout.block.render"

[[extensions.targeting.metafields]]
key = "my-key"
unique_id = "my-namespace"

[settings]
[[settings.fields]]
key = "banner_title"
type = "single_line_text_field"
name = "Banner title"
description = "Enter a title for the banner"
```

--------------------------------

### Render Subscriptions in Order Action Target

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/targets/order-actions

This example demonstrates how to fetch and display a customer's subscriptions within an order action target. It includes handling loading states and empty subscription lists. Ensure your API endpoint is correctly configured.

```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useState, useEffect} from 'preact/hooks';

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

function Extension() {
  const [subscriptions, setSubscriptions] = useState(null);

  useEffect(() => {
    async function fetchSubscriptions() {
      const token = await shopify.sessionToken.get();
      const res = await fetch('https://your-app.com/api/subscriptions', {
        headers: {Authorization: `Bearer ${token}`},
      });
      const data = await res.json();
      setSubscriptions(data.subscriptions);
    }
    fetchSubscriptions();
  }, []);

  if (!subscriptions) {
    return (
      <s-section heading="Subscriptions">
        <s-spinner size="base" />
      </s-section>
    );
  }

  if (subscriptions.length === 0) {
    return null;
  }

  return (
    <s-section heading="Subscriptions">
      <s-stack direction="block" gap="base">
        {subscriptions.map((sub) => (
          <s-stack key={sub.id} direction="inline" gap="base">
            <s-text type="strong">{sub.productName}</s-text>
            <s-badge>{sub.status}</s-badge>
            <s-text color="subdued">
              Next billing: {sub.nextBillingDate}
            </s-text>
          </s-stack>
        ))}
      </s-stack>
    </s-section>
  );
}
```

--------------------------------

### Collect a First Name

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/forms/text-field

Add a single-line text input with a pre-filled value. This example displays a text field with an optional label and a defaultValue.

```html
<s-text-field
label="First name (optional)"
defaultValue="Taylor"
></s-text-field>
```

--------------------------------

### Set an aspect ratio

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/media-and-visuals/image

Compare different aspect ratios on the same image. This example stacks a 1:1 square crop above a 16:9 widescreen crop, both using `objectFit="cover"` to fill their containers.

```html
<s-stack gap="base">
<s-image
  src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
  alt="Indoor plant in a gray pot"
  aspectRatio="1/1"
  inlineSize="fill"
  objectFit="cover"
></s-image>
<s-image
  src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
  alt="Indoor plant in a gray pot"
  aspectRatio="16/9"
  inlineSize="fill"
  objectFit="cover"
></s-image>
</s-stack>
```