Shopify App Home

https://shopify.dev/docs/api/app-home
Admin
Shopify App Home is the primary interface within the Shopify admin where merchants interact with...
Tokens:489,577
Snippets:4,266
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Expandable setup guide with completion tracking

Source: https://shopify.dev/docs/api/app-home/latest/patterns/compositions/setup-guide

Interactive checklist for onboarding or setup tasks. Uses useState to manage expanded state for the guide and each step, with checkboxes for completion tracking and a progress indicator.

```tsx
// @framework-globals: useState
const [expanded, setExpanded] = useState({
  guide: true,
  step1: true,
  step2: false,
  step3: false,
});

return (
<s-section>
  <s-grid gap="base">
    <s-grid gap="small-200">
      <s-grid
        gridTemplateColumns="1fr auto auto"
        gap="small-300"
        alignItems="center"
      >
        <s-heading>Setup Guide</s-heading>
        <s-button
          accessibilityLabel="Dismiss Guide"
          variant="tertiary"
          tone="neutral"
          icon="x"
         />
        <s-button
          accessibilityLabel="Toggle setup guide"
          variant="tertiary"
          tone="neutral"
          onClick={() => setExpanded({ ...expanded, guide: !expanded.guide })}
          icon={expanded.guide ? "chevron-up" : "chevron-down"}
         />
      </s-grid>
      <s-paragraph>
        Use this personalized guide to get your store ready for sales.
      </s-paragraph>
      <s-paragraph color="subdued">0 out of 3 steps completed</s-paragraph>
    </s-grid>
    <s-box
      borderRadius="base"
      border="base"
      background="base"
      display={expanded.guide ? "auto" : "none"}
    >
      <s-box>
        <s-grid gridTemplateColumns="1fr auto" gap="base" padding="small">
          <s-checkbox label="Upload an image for your puzzle" />
          <s-button
            accessibilityLabel="Toggle step 1 details"
            variant="tertiary"
            onClick={() => setExpanded({ ...expanded, step1: !expanded.step1 })}
            icon={expanded.step1 ? "chevron-up" : "chevron-down"}
           />
        </s-grid>
        <s-box
          padding="small"
          paddingBlockStart="none"
          display={expanded.step1 ? "auto" : "none"}
        >
          <s-box padding="base" background="subdued" borderRadius="base">
            <s-grid
              gridTemplateColumns="1fr auto"
              gap="base"
              alignItems="center"
            >
              <s-grid gap="small-200">
                <s-paragraph>
                  Start by uploading a high-quality image that will be used to
                  create your puzzle. For best results, use images that are at
                  least 1200x1200 pixels.
                </s-paragraph>
                <s-stack direction="inline" gap="small-200">
                  <s-button variant="primary">Upload image</s-button>
                  <s-button variant="tertiary" tone="neutral">
                    {" "}
                    Image requirements{" "}
                  </s-button>
                </s-stack>
              </s-grid>
              <s-box maxBlockSize="80px" maxInlineSize="80px">
                <s-image
                  src="https://cdn.shopify.com/s/assets/admin/checkout/settings-customizecart-705f57c725ac05be5a34ec20c05b94298cb8afd10aac7bd9c7ad02030f48cfa0.svg"
                  alt="Customize checkout illustration"
                 />
              </s-box>
            </s-grid>
          </s-box>
        </s-box>
      </s-box>
      <s-divider />
      <s-box>
        <s-grid gridTemplateColumns="1fr auto" gap="base" padding="small">
          <s-checkbox label="Choose a puzzle template" />
          <s-button
            accessibilityLabel="Toggle step 2 details"
            variant="tertiary"
            onClick={() => setExpanded({ ...expanded, step2: !expanded.step2 })}
            icon={expanded.step2 ? "chevron-up" : "chevron-down"}
           />
        </s-grid>
        <s-box
          padding="small"
          paddingBlockStart="none"
          display={expanded.step2 ? "auto" : "none"}
        >
          <s-box padding="base" background="subdued" borderRadius="base">
            <s-grid
              gridTemplateColumns="1fr auto"
              gap="base"
              alignItems="center"
            >
              <s-grid gap="small-200">
                <s-paragraph>
                  Choose from our library of puzzle templates including classic
                  jigsaw, hexagonal, and irregular shapes.
                </s-paragraph>
                <s-stack direction="inline" gap="small-200">
                  <s-button variant="primary">Browse templates</s-button>
                </s-stack>
              </s-grid>
              <s-box maxBlockSize="80px" maxInlineSize="80px">
                <s-image
                  src="https://cdn.shopify.com/s/assets/admin/checkout/settings-customizecart-705f57c725ac05be5a34ec20c05b94298cb8afd10aac7bd9c7ad02030f48cfa0.svg"
                  alt="Customize checkout illustration"
                 />
              </s-box>
            </s-grid>
          </s-box>
        </s-box>
      </s-box>
      <s-divider />
      <s-box>
        <s-grid gridTemplateColumns="1fr auto" gap="base" padding="small">
          <s-checkbox label="Set up your store details" />
          <s-button
            accessibilityLabel="Toggle step 3 details"
            variant="tertiary"
            onClick={() => setExpanded({ ...expanded, step3: !expanded.step3 })}
            icon={expanded.step3 ? "chevron-up" : "chevron-down"}
           />
        </s-grid>
        <s-box
          padding="small"
          paddingBlockStart="none"
          display={expanded.step3 ? "auto" : "none"}
        >
          <s-box padding="base" background="subdued" borderRadius="base">
            <s-grid
              gridTemplateColumns="1fr auto"
              gap="base"
              alignItems="center"
            >
              <s-grid gap="small-200">
                <s-paragraph>
                  Add your store name, address, and contact information to
                  complete your setup.
                </s-paragraph>
                <s-stack direction="inline" gap="small-200">
                  <s-button variant="primary">Set up store details</s-button>
                </s-stack>
              </s-grid>
              <s-box maxBlockSize="80px" maxInlineSize="80px">
                <s-image
                  src="https://cdn.shopify.com/s/assets/admin/checkout/settings-customizecart-705f57c725ac05be5a34ec20c05b94298cb8afd10aac7bd9c7ad02030f48cfa0.svg"
                  alt="Customize checkout illustration"
                 />
              </s-box>
            </s-grid>
          </s-box>
        </s-box>
      </s-box>
    </s-box>
  </s-grid>
</s-section>
);
```

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

### Setup Guide JSX with s-section and s-grid

Source: https://shopify.dev/docs/api/app-home/latest/patterns/compositions/setup-guide

Renders a setup guide panel with a header, progress text, and three checklist steps. Each step uses s-checkbox with onChange handlers that call shopify.toast.show. Includes expandable step details and template browsing UI.

```tsx
<s-section>
  <s-grid gap="base">
    <s-grid gap="small-200">
      <s-grid
        gridTemplateColumns="1fr auto auto"
        gap="small-300"
        alignItems="center"
      >
        <s-heading>Setup Guide</s-heading>
        <s-button
          accessibilityLabel="Dismiss Guide"
          variant="tertiary"
          tone="neutral"
          icon="x"
        />
        <s-button
          accessibilityLabel="Toggle setup guide"
          variant="tertiary"
          tone="neutral"
          icon="chevron-up"
        />
      </s-grid>
      <s-paragraph>
        Use this personalized guide to get your store ready for sales.
      </s-paragraph>
      <s-paragraph color="subdued">1 out of 3 steps completed</s-paragraph>
    </s-grid>
    <s-box borderRadius="base" border="base" background="base">
      <s-box>
        <s-grid gridTemplateColumns="1fr auto" gap="base" padding="small">
          <s-checkbox
            label="Upload an image for your puzzle"
            checked
            onChange={() => {
              shopify.toast.show('Step 1 completed!');
            }}
          />
          <s-button
            accessibilityLabel="Toggle step 1 details"
            variant="tertiary"
            icon="chevron-down"
          />
        </s-grid>
      </s-box>
      <s-divider />
      <s-box>
        <s-grid gridTemplateColumns="1fr auto" gap="base" padding="small">
          <s-checkbox
            label="Choose a puzzle template"
            onChange={() => {
              shopify.toast.show('Step 2 completed!');
            }}
          />
          <s-button
            accessibilityLabel="Toggle step 2 details"
            variant="tertiary"
            icon="chevron-up"
          />
        </s-grid>
        <s-box padding="small" paddingBlockStart="none">
          <s-box padding="base" background="subdued" borderRadius="base">
            <s-grid
              gridTemplateColumns="1fr auto"
              gap="base"
              alignItems="center"
            >
              <s-grid gap="small-200">
                <s-paragraph>
                  Choose from our library of puzzle templates or create your own custom layout.
                </s-paragraph>
                <s-stack direction="inline" gap="small-200">
                  <s-button variant="primary">Browse templates</s-button>
                </s-stack>
              </s-grid>
              <s-box maxBlockSize="80px" maxInlineSize="80px">
                <s-image
                  src="https://cdn.shopify.com/s/assets/admin/checkout/settings-customizecart-705f57c725ac05be5a34ec20c05b94298cb8afd10aac7bd9c7ad02030f48cfa0.svg"
                  alt="Templates illustration"
                />
              </s-box>
            </s-grid>
          </s-box>
        </s-box>
      </s-box>
      <s-divider />
      <s-box>
        <s-grid gridTemplateColumns="1fr auto" gap="base" padding="small">
          <s-checkbox
            label="Customize puzzle piece shapes"
            onChange={() => {
              shopify.toast.show('Step 3 completed!');
            }}
          />
          <s-button
            accessibilityLabel="Toggle step 3 details"
            variant="tertiary"
            icon="chevron-down"
          />
        </s-grid>
      </s-box>
    </s-box>
  </s-grid>
</s-section>
```

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

### Example: Add a numbered step list

Source: https://shopify.dev/docs/api/app-home-ui-extension/latest/web-components/layout-and-structure/ordered-list

Create a numbered list of sequential steps. This example shows a basic ordered list with three setup instructions.

```APIDOC
## Example: Add a numbered step list

### Description
Create a numbered list of sequential steps. This example shows a basic ordered list with three setup instructions.
```

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

### Example: Create a two-column layout

Source: https://shopify.dev/docs/api/app-home/latest/web-components/layout-and-structure/grid

Create a simple two-column layout. This example uses a 12-column grid system with equal-width columns.

```APIDOC
## Example: Create a two-column layout

### Description
Create a simple two-column layout. This example uses a 12-column grid system with equal-width columns.

### Code
```html
<s-grid gridTemplateColumns="repeat(12, 1fr)" gap="base">
  <s-grid-item gridColumn="span 6" gridRow="span 1">
    <s-section>
      <s-text>Left column</s-text>
    </s-section>
  </s-grid-item>
  <s-grid-item gridColumn="span 6" gridRow="span 1">
    <s-section>
      <s-text>Right column</s-text>
    </s-section>
  </s-grid-item>
</s-grid>
```
```

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

### Start local development server

Source: https://shopify.dev/docs/api/app-home

Run the Shopify CLI dev command to start a local server and create a tunnel for testing your app in a development store.

```bash
shopify app dev
```

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

### Homepage with banner, setup guide, and product list (JSX)

Source: https://shopify.dev/docs/api/app-home/latest/patterns/templates/homepage

This JSX snippet renders a homepage for a Product Quality Auditor app. It includes a banner, a setup guide with steps, and a product list. The component uses useState to manage visibility and expansion of sections, and tracks progress through the setup steps.

```tsx
// @framework-globals: useState
const [visible, setVisible] = useState({
  banner: true,
  setupGuide: true,
  calloutCard: true,
  featuredApps: true,
});
const [expanded, setExpanded] = useState({
  setupGuide: true,
  step1: false,
  step2: false,
  step3: false,
});
const [progress, setProgress] = useState(0);

return (
  <s-page>
      <s-button slot="primary-action">Create puzzle</s-button>
      <s-button slot="secondary-actions">Browse templates</s-button>
      <s-button slot="secondary-actions">Import image</s-button>

      {/* === */}
      {/* Banner */}
      {/* Use banners sparingly. Only one banner should be visible at a time. */}
      {/* If dismissed, use local storage or a database entry to avoid showing this section again to the same user. */}
      {/* === */}
      {visible.banner && (
        <s-banner
          dismissible
          onDismiss={() => setVisible({ ...visible, banner: false })}
        >
          3 of 5 puzzles created.{" "}
          <s-link href="#">Upgrade to Puzzlify Pro</s-link> to create unlimited
          puzzles.
        </s-banner>
      )}

      {/* === */}
      {/* Setup Guide */}
      {/* Keep instructions brief and direct. Only ask merchants for required information. */}
      {/* If dismissed, use local storage or a database entry to avoid showing this section again to the same user. */}
      {/* === */}
      {visible.setupGuide && (
        <s-section>
          <s-grid gap="small">
            {/* Header */}
            <s-grid gap="small-200">
              <s-grid
                gridTemplateColumns="1fr auto auto"
                gap="small-300"
                alignItems="center"
              >
                <s-heading>Setup Guide</s-heading>
                <s-button
                  accessibilityLabel="Dismiss Guide"
                  onClick={() => setVisible({ ...visible, setupGuide: false })}
                  variant="tertiary"
                  tone="neutral"
                  icon="x"
                ></s-button>
                <s-button
                  accessibilityLabel="Toggle setup guide"
                  onClick={(e) =>
                    setExpanded({
                      ...expanded,
                      setupGuide: !expanded.setupGuide,
                    })
                  }
                  variant="tertiary"
                  tone="neutral"
                  icon={expanded.setupGuide ? "chevron-up" : "chevron-down"}
                ></s-button>
              </s-grid>
              <s-paragraph>
                Use this personalized guide to get your store ready for sales.
              </s-paragraph>
              <s-paragraph color="subdued">
                {progress} out of 3 steps completed
              </s-paragraph>
            </s-grid>
            {/* Steps Container */}
            <s-box
              borderRadius="base"
              border="base"
              background="base"
              display={expanded.setupGuide ? "auto" : "none"}
            >
              {/* Step 1 */}
              <s-box>
                <s-grid
                  gridTemplateColumns="1fr auto"
                  gap="base"
                  padding="small"
                >
                  <s-checkbox
                    label="Upload an image for your puzzle"
                    onInput={(e) =>
                      setProgress(e.currentTarget.checked ? progress + 1 : progress - 1)
                    }
                  ></s-checkbox>
                  <s-button
                    onClick={(e) => {
                      setExpanded({ ...expanded, step1: !expanded.step1 });
                    }}
                    accessibilityLabel="Toggle step 1 details"
                    variant="tertiary"
                    icon={expanded.step1 ? "chevron-up" : "chevron-down"}
                  ></s-button>
                </s-grid>
                <s-box
                  padding="small"
                  paddingBlockStart="none"
                  display={expanded.step1 ? "auto" : "none"}
                >
                  <s-box
                    padding="base"
                    background="subdued"
                    borderRadius="base"
                  >
                    <s-grid
                      gridTemplateColumns="1fr auto"
                      gap="base"
                      alignItems="center"
                    >
                      <s-grid gap="small-200">
                        <s-paragraph>
                          Start by uploading a high-quality image that will be

```

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

### Navigation menu example

Source: https://shopify.dev/docs/api/app-home/app-bridge-web-components/app-nav

An example of an app-nav component where the home page is set to '/app' using an s-link with rel='home', which hides the link from the rendered menu.

```html
<s-app-nav>
<s-link href="/app" rel="home">Home</s-link>
<s-link href="/app/templates">Templates</s-link>
<s-link href="/app/settings">Settings</s-link>
</s-app-nav>
```

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

### Example: Build layouts with column spans

Source: https://shopify.dev/docs/api/app-home/latest/web-components/layout-and-structure/grid

Use a 12-column grid system with spans to create full-width, half-width, and third-width column arrangements. This example shows multiple rows with progressively narrower columns.

```APIDOC
## Example: Build layouts with column spans

### Description
Use a 12-column grid system with spans to create full-width, half-width, and third-width column arrangements. This example shows multiple rows with progressively narrower columns.

### Code
```html
<s-grid gridTemplateColumns="repeat(12, 1fr)" gap="base">
  <s-grid-item gridColumn="span 12" gridRow="span 1">
    <s-section>
      <s-text>Full width</s-text>
    </s-section>
  </s-grid-item>
  <s-grid-item gridColumn="span 6" gridRow="span 1">
    <s-section>
      <s-text>Half width</s-text>
    </s-section>
  </s-grid-item>
  <s-grid-item gridColumn="span 4" gridRow="span 1">
    <s-section>
      <s-text>Third width</s-text>
    </s-section>
  </s-grid-item>
</s-grid>
```
```

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

### Example: Display notification list

Source: https://shopify.dev/docs/api/app-home/latest/web-components/overlays/popover

Shows how to surface time-sensitive information on demand.

```APIDOC
## Example: Display notification list

### Description
Surface time-sensitive information on demand. This example displays a notification list with order, inventory, and payment alerts.

```

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

### Get location information

Source: https://shopify.dev/docs/api/app-home/latest/apis/device-and-platform-integration/pos-api

Retrieves POS location information. The example gets the location ID, name, and status.

```APIDOC
## Get location information

### Description
Retrieves POS location information.

### Method
Not specified (SDK method)

### Endpoint
shopify.pos.location

### Parameters
None

### Request Example
```js
await shopify.pos.location();
```

### Response
No response details provided.
```

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

### Initialize Shopify app with Shopify CLI

Source: https://shopify.dev/docs/api/app-home

Initializes a new Shopify app in the current directory using the Shopify CLI. Run this command from the my-app directory to scaffold a new app project.

```bash
cd my-app
shopify app init
```

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

### Get device information

Source: https://shopify.dev/docs/api/app-home/latest/apis/device-and-platform-integration/pos-api

Retrieves POS device information. The example gets the device name and serial number.

```APIDOC
## Get device information

### Description
Retrieves POS device information.

### Method
Not specified (SDK method)

### Endpoint
shopify.pos.device

### Parameters
None

### Request Example
```js
await shopify.pos.device();
```

### Response
No response details provided.
```

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

### Example: Show a menu of actions

Source: https://shopify.dev/docs/api/app-home/latest/web-components/overlays/popover

Shows how to display contextual options without navigating away from the current page.

```APIDOC
## Example: Show a menu of actions

### Description
Show contextual options without navigating away from the current page. This example presents an action menu with edit and delete options.

### HTML
```html
<s-button commandFor="product-options-popover">Product options</s-button>

<s-popover id="product-options-popover">
  <s-stack direction="block">
    <s-button variant="tertiary">Import</s-button>
    <s-button variant="tertiary">Export</s-button>
  </s-stack>
</s-popover>
```

```

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

### Launch article creation workflow

Source: https://shopify.dev/docs/api/app-home-ui-extension/latest/target-apis/utility-apis/intents-api

Launch the article creation workflow from a button click. This example uses `shopify.intents.invoke()` to open the article editor, awaits the workflow completion, and displays success or cancellation feedback based on the response code.

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

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

function Extension() {
  const [result, setResult] = useState(null);
  const [creating, setCreating] = useState(false);

  const handleCreate = async () => {
    setCreating(true);
    
    const activity = await shopify.intents.invoke('create:shopify/Article');
    const response = await activity.complete;

    setResult(response);
    setCreating(false);
  };

  return (
    <s-page heading="Create Article">
      <s-button onClick={handleCreate} disabled={creating}>
        {creating ? 'Creating...' : 'Launch Article Creator'}
      </s-button>
      {result?.code === 'ok' && (
        <s-banner tone="success">Article created successfully!</s-banner>
      )}
      {result?.code === 'closed' && (
        <s-text>Creation cancelled</s-text>
      )}
    </s-page>
  );
}
```

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

### Basic s-page component with banner and section

Source: https://shopify.dev/docs/api/app-home/latest/web-components/layout-and-structure/page

Example of an s-page component with a heading, a warning banner in the supplemental-start slot, and a section with a paragraph. Use this as a starting point for building a page layout.

```html
<s-page heading="Orders">
  <s-banner slot="supplemental-start" tone="warning" heading="Payouts are paused">
    <s-paragraph>Verify your bank account to resume payouts.</s-paragraph>
  </s-banner>
  <s-section heading="Unfulfilled">
    <s-paragraph>You have 3 orders waiting to be fulfilled.</s-paragraph>
  </s-section>
</s-page>
```

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

### Show an error with help text

Source: https://shopify.dev/docs/api/app-home-ui-extension/latest/web-components/forms/email-field

Display an error message and help text to guide merchants toward entering a valid email. This example shows a required email field with both a details hint and an error message.

```html
<s-stack gap="base">
  <s-email-field
    label="Contact email"
    details="We'll send your order confirmation here"
    error="Please enter a valid email address"
    required
  ></s-email-field>
</s-stack>
```

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

### Settings menu with sections and sign-out

Source: https://shopify.dev/docs/api/app-home-ui-extension/latest/web-components/actions/menu

Builds a settings-style menu with account and store sections plus a root-level sign-out link.

```html
<s-button icon="settings" commandFor="admin-settings">Settings</s-button>


<s-menu id="admin-settings" accessibilityLabel="Settings menu">
  <s-section heading="Account">
    <s-button icon="profile">Profile settings</s-button>
    <s-button icon="lock">Security</s-button>
    <s-button>Billing information</s-button>
  </s-section>
  <s-section heading="Store">
    <s-button icon="store">Store settings</s-button>
    <s-button>Payment providers</s-button>
    <s-button icon="delivery">Shipping rates</s-button>
  </s-section>
  <s-button href="javascript:void(0)" icon="person-exit">Sign out</s-button>
</s-menu>
```

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

### Create a warning banner with buttons for next steps

Source: https://shopify.dev/docs/api/app-home/latest/web-components/feedback-and-status-indicators/banner

Use this snippet to create a warning banner with secondary action buttons for next steps. The buttons are placed in the secondary-actions slot and link to relevant resources, such as a product review page and a setup guide.

```html
<s-banner heading="127 products missing shipping weights" tone="warning">
  Products without weights may show inaccurate shipping rates, leading to
  checkout abandonment.
  <s-button
    slot="secondary-actions"
    variant="secondary"
    href="/admin/products?filter=missing-weights"
  >
    Review products
  </s-button>
  <s-button
    slot="secondary-actions"
    variant="secondary"
    href="javascript:void(0)"
  >
    Setup guide
  </s-button>
</s-banner>
```

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

### Scaffold a new app with Shopify CLI

Source: https://shopify.dev/docs/api/app-home-ui-extension/latest

Use this command to initialize a new extension-only app project.

```terminal
shopify app init

# select "Build an extension-only app" when prompted
```

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

### s-text-field Examples

Source: https://shopify.dev/docs/api/app-home/latest/web-components/forms/text-field

Examples of using the s-text-field component: basic text field, with icon, and with error messages.

```APIDOC
## s-text-field Examples

### Add a basic text field

```html
<s-text-field
  label="Store name"
  value="Jaded Pixel"
  placeholder="Become a merchant"
></s-text-field>
```

### Add an icon to a text field

```html
<s-text-field
  label="Search"
  icon="search"
  placeholder="Search products..."
></s-text-field>
```

### Provide specific error messages for merchant context

```html
<s-text-field
  label="Store name"
  error="Store name is required"
></s-text-field>
```

```

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

### Deploy app to production

Source: https://shopify.dev/docs/api/app-home

Use the Shopify CLI deploy command to sync your app's configuration and extensions to Shopify after hosting your app.

```bash
shopify app deploy
```

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

### HTML usage example for s-avatar component

Source: https://shopify.dev/docs/api/app-home/latest/web-components/media-and-visuals/avatar

Basic example of using the `s-avatar` web component with `alt` and `initials` attributes.

```html
<s-avatar alt="John Doe" initials="JD"></s-avatar>
```

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

### Implement Resource Picker in a UI Extension

Source: https://shopify.dev/docs/api/app-home-ui-extension/latest/target-apis/utility-apis/resource-picker-api

This example demonstrates how to trigger the resource picker to select products matching a specific query and display the count of selected items.

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

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

function Extension() {
  const [selected, setSelected] = useState(null);

  const handlePick = async () => {
    const result = await shopify.resourcePicker({
      type: 'product',
      query: 'shirt',
    });
    setSelected(result);
  };

  return (
    <s-page heading="Resource Picker">
      <s-button onClick={handlePick}>Select Products</s-button>
      {selected && <s-text>{selected.length} products selected</s-text>}
    </s-page>
  );
}
```

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

### Basic switch example

Source: https://shopify.dev/docs/api/app-home-ui-extension/latest/web-components/forms/switch

Use this HTML snippet to render a switch component with a label and details. The switch is ideal for binary settings that take effect immediately, such as enabling features or activating settings.

```html
<s-switch
  label="Enable feature"
  details="Ensure all criteria are met before enabling"
></s-switch>
```

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

### Open Resource Picker with Search Query

Source: https://shopify.dev/docs/api/app-home/latest/apis/user-interface-and-interactions/resource-picker-api

Initializes the resource picker with a pre-filled search query using the query option.

```js
const selected = await shopify.resourcePicker({
  type: 'product',
  query: 'Sweater',
});
```

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

### Date picker component for form example

Source: https://shopify.dev/docs/api/app-home/latest/web-components/forms/date-picker

This is the date picker component used in the form example above. It is a range picker with a pre-selected range and a specific month view.

```html
<s-date-picker
  type="range"
  name="order-date-range"
  value="2024-01-01--2024-01-31"
  view="2024-01"
></s-date-picker>
```

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

### Display a product thumbnail

Source: https://shopify.dev/docs/api/app-home-ui-extension/latest/web-components/media-and-visuals/image

Example demonstrating how to display a product thumbnail with metadata in a grid layout, controlling image sizing with aspectRatio, objectFit, and inlineSize, and rounding corners with borderRadius.

```APIDOC
## Display a product thumbnail

### Description
Display a product thumbnail with metadata in a grid layout. This example demonstrates how to control image sizing with `aspectRatio`, `objectFit`, and `inlineSize`, and round corners with `borderRadius`.

### Example
```html
<s-grid gridTemplateColumns="80px 1fr" gap="base" alignItems="center">
  <s-image
    src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
    alt="Indoor plant"
    aspectRatio="1/1"
    objectFit="cover"
    borderRadius="base"
    inlineSize="fill"
  />
  <s-stack gap="small">
    <s-text type="strong">Indoor Plant</s-text>
    <s-text color="subdued">SKU: PLT-001</s-text>
    <s-text tone="success">In stock</s-text>
  </s-stack>
</s-grid>
```
```

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

### s-color-field example with validation

Source: https://shopify.dev/docs/api/app-home/latest/web-components/forms/color-field

Example usage of the s-color-field component inside an s-section with an s-stack. The color field includes a label, name, invalid value, error message, and required attribute.

```html
<s-section>
  <s-stack gap="base" justifyContent="start">
    <s-text-field label="Theme name"></s-text-field>
    <s-color-field
      label="Brand color"
      name="Color"
      value="#invalid"
      error="Please enter a valid color format"
      required
    ></s-color-field>
  </s-stack>
</s-section>
```

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

### Create a Product using Intents API

Source: https://shopify.dev/docs/api/app-home-ui-extension/latest/target-apis/utility-apis/intents-api

Launch the product creation workflow to add a new item to the store catalog. This example invokes the create intent, tracks loading state, and displays feedback on completion.

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

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

function Extension() {
  const [result, setResult] = useState(null);
  const [creating, setCreating] = useState(false);

  const handleCreate = async () => {
    setCreating(true);

    const activity = await shopify.intents.invoke('create:shopify/Product');
    const response = await activity.complete;

    setResult(response);
    setCreating(false);
  };

  return (
    <s-page heading="Create Product">
      <s-button onClick={handleCreate} disabled={creating}>
        {creating ? 'Creating...' : 'Launch Product Creator'}
      </s-button>
      {result?.code === 'ok' && (
        <s-banner tone="success">
          Product created: {result.data?.product?.id}
        </s-banner>
      )}
      {result?.code === 'closed' && (
        <s-text>Creation cancelled</s-text>
      )}
    </s-page>
  );
}
```

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

### Add products with Resource Picker API (HTML)

Source: https://shopify.dev/docs/api/app-home/latest/patterns/compositions/resource-list

HTML version of the resource list example. The 'Add products' button is static; the resource picker handler is provided in an HTML comment below the markup.

```html
<s-section padding="none">
  <s-stack gap="small-200">
    <s-grid gridTemplateColumns="1fr auto" gap="base" alignItems="center" paddingInline="base" paddingBlockStart="base">
      <s-text-field icon="search" placeholder="Filter products"></s-text-field>
      <s-button>Add products</s-button>
    </s-grid>
    
    <s-grid gridTemplateColumns="1fr auto" gap="base" alignItems="center" paddingInline="base">
      <s-text>Showing 2 products</s-text>
      <s-select>
        <s-option value="newest">Newest</s-option>
        <s-option value="oldest">Oldest</s-option>
      </s-select>
    </s-grid>
    
    <s-stack>
      <s-clickable borderStyle="solid none none none" border="base" paddingInline="base" paddingBlock="small">
        <s-grid gridTemplateColumns="auto 1fr auto" gap="base" alignItems="center">
          <s-thumbnail
            size="small"
            src="https://picsum.photos/id/29/80/80"
            alt="Mountain View puzzle"
          ></s-thumbnail>
          <s-stack>
            <s-heading>Mountain View</s-heading>
            <s-text>16 pieces</s-text>
          </s-stack>
          <s-button icon="menu-horizontal" variant="tertiary" accessibilityLabel="Actions for Mountain View"></s-button>
        </s-grid>
      </s-clickable>
      <s-clickable borderStyle="solid none none none" border="base" paddingInline="base" paddingBlock="small">
        <s-grid gridTemplateColumns="auto 1fr auto" gap="base" alignItems="center">
          <s-thumbnail
            size="small"
            src="https://picsum.photos/id/12/80/80"
            alt="Ocean Sunset puzzle"
          ></s-thumbnail>
          <s-stack>
            <s-heading>Ocean Sunset</s-heading>
            <s-text>9 pieces</s-text>
          </s-stack>
          <s-button icon="menu-horizontal" variant="tertiary" accessibilityLabel="Actions for Ocean Sunset"></s-button>
        </s-grid>
      </s-clickable>
    </s-stack>
  </s-stack>
</s-section>

<!-- 
Add products handler:
const selected = await shopify.resourcePicker({
  type: 'product',
  multiple: true,
});
if (selected) {
  console.log('Selected products:', selected);
}
-->
```

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

### Choice list HTML example

Source: https://shopify.dev/docs/api/app-home-ui-extension/latest/web-components/forms/choice-list

Example of the s-choice-list web component with a script that logs selected values on change. The component includes a label, name, details, and three s-choice options.

```html
<script>
  const handleChange = (event) =>
    console.log('Values: ', event.currentTarget.values);
</script>
<s-choice-list
  label="Company name"
  name="Company name"
  details="The company name will be displayed on the checkout page."
  onChange="handleChange(event)"
>
  <s-choice value="hidden">Hidden</s-choice>
  <s-choice value="optional">Optional</s-choice>
  <s-choice value="required">Required</s-choice>
</s-choice-list>
```

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

### Launch catalog creation workflow

Source: https://shopify.dev/docs/api/app-home-ui-extension/latest/target-apis/utility-apis/intents-api

Launch the catalog creation workflow to set up B2B customer groups or market-specific product collections. This example invokes the create intent, manages loading state, and displays success or cancellation feedback.

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

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

function Extension() {
  const [result, setResult] = useState(null);
  const [loading, setLoading] = useState(false);

  const handleAction = async () => {
    setLoading(true);
    
    const activity = await shopify.intents.invoke('create:shopify/Catalog');
    const response = await activity.complete;

    setResult(response);
    setLoading(false);
  };

  return (
    <s-page heading="Create Catalog">
      <s-button onClick={handleAction} disabled={loading}>
        {loading ? 'Creating...' : 'Launch Catalog Creator'}
      </s-button>
      {result?.code === 'ok' && (
        <s-banner tone="success">Catalog created successfully!</s-banner>
      )}
      {result?.code === 'closed' && (
        <s-text>Creation cancelled</s-text>
      )}
    </s-page>
  );
}
```

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

### Example: Add a grid layout with column spans

Source: https://shopify.dev/docs/api/app-home/latest/web-components/layout-and-structure/grid

Create a grid layout with columns and grid items that span them. This example shows a two-column grid with a full-width header row and two equal columns below.

```APIDOC
## Example: Add a grid layout with column spans

### Description
Create a grid layout with columns and grid items that span them. This example shows a two-column grid with a full-width header row and two equal columns below.

### Code
```html
<s-grid
  gridTemplateColumns="repeat(2, 1fr)"
  gap="small"
  justifyContent="center"
>
  <s-grid-item gridColumn="span 2" border="base" borderStyle="dashed">
    Summary of sales
  </s-grid-item>
  <s-grid-item gridColumn="span 1" border="base" borderStyle="dashed">
    Orders
  </s-grid-item>
  <s-grid-item gridColumn="auto" border="base" borderStyle="dashed">
    Customers
  </s-grid-item>
</s-grid>
```
```

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

### Method: show

Source: https://shopify.dev/docs/api/app-home/latest/app-bridge-web-components/app-window

Opens the app window and displays the content from the src URL. Returns a Promise that resolves when the window is fully visible. Commonly used for launching workflows.

```APIDOC
## [METHOD] show

### Description
Opens the app window and displays the content from the `src` URL. Returns a Promise that resolves when the window is fully visible. Use `await` or `.then()` to run code after the window opens. Commonly used for launching workflows triggered by user actions.

### Signature
```typescript
show(): Promise<void>
```

### Returns
Promise<void> - Resolves when the window is fully visible.

### Example
```javascript
const appWindow = document.querySelector('app-window');
await appWindow.show();
```
```

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

### HTML example: s-button-group with secondary actions

Source: https://shopify.dev/docs/api/app-home/latest/web-components/actions/button-group

Use this HTML snippet to create a button group with secondary actions. The example includes a Cancel button and a critical-tone Delete product button, both placed in the secondary-actions slot.

```html
<s-button-group>
  <s-button slot="secondary-actions">Cancel</s-button>
  <s-button slot="secondary-actions" tone="critical">Delete product</s-button>
</s-button-group>
```

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

### Open product resource picker

Source: https://shopify.dev/docs/api/app-home/latest/apis/user-interface-and-interactions/resource-picker-api

Opens a product resource picker and handles the selection response, returning an array of product objects.

```js
const selected = await shopify.resourcePicker({type: 'product'});
```

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

### shopify.intents.invoke('create:shopify/Market')

Source: https://shopify.dev/docs/api/app-home-ui-extension/latest/target-apis/utility-apis/intents-api

Launches the market creation workflow for international selling with region-specific configurations. This example invokes the create intent, manages loading state, and displays feedback on completion.

```APIDOC
## shopify.intents.invoke('create:shopify/Market')

### Description
Launches the market creation workflow for international selling with region-specific configurations. This example invokes the create intent, manages loading state, and displays feedback on completion.

### Method
invoke

### Endpoint
shopify.intents.invoke('create:shopify/Market')

### Parameters
No parameters are documented for this intent.

### Request Example
```tsx
const activity = await shopify.intents.invoke('create:shopify/Market');
const response = await activity.complete;
```

### Response
#### Success Response
- **code** (string) - 'ok' if the market was created, 'closed' if creation was cancelled.

#### Response Example
```json
{
  "code": "ok"
}
```

```

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

### useAppBridge hook example in tsx

Source: https://shopify.dev/docs/api/app-home/latest/apis/react-hooks/useappbridge

Shows how to use the useAppBridge hook in a React component to access the shopify global and call the toast API. The example defines a GenerateBlogPostButton component that displays a toast notification when clicked.

```tsx
import {useAppBridge} from '@shopify/app-bridge-react';

export function GenerateBlogPostButton() {
  const shopify = useAppBridge();

  function generateBlogPost() {
    // Handle generating
    shopify.toast.show('Blog post template generated');
  }

  return <button onClick={generateBlogPost}>Generate Blog Post</button>;
}
```

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

### Sales report form with start and end date fields

Source: https://shopify.dev/docs/api/app-home/latest/web-components/forms/date-field

Use this form to collect a start and end date for a sales report. It includes two s-date-field components with labels and IDs, and a primary button to generate the report.

```html
<s-stack gap="base">
  <s-heading>Sales report period</s-heading>


  <s-stack direction="inline" gap="base">
    <s-date-field
      label="Start date"
      name="startDate"
      id="report-start"
    ></s-date-field>


    <s-date-field
      label="End date"
      name="endDate"
      id="report-end"
    ></s-date-field>
  </s-stack>


  <s-button variant="primary">Generate report</s-button>
</s-stack>
```

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

### Preselect products

Source: https://shopify.dev/docs/api/app-home/latest/apis/user-interface-and-interactions/resource-picker-api

Opens the resource picker with products already selected by passing GIDs to the selectionIds option.

```js
const selected = await shopify.resourcePicker({
  type: 'product',
  selectionIds: [
    {
      id: 'gid://shopify/Product/12345',
      variants: [
        {
          id: 'gid://shopify/ProductVariant/1',
        },
      ],
    },
    {
      id: 'gid://shopify/Product/67890',
    },
  ],
});
```
Tokens:
Raw