> ## Documentation Index
> Fetch the complete documentation index at: https://swish.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install Swish and add your first shopping tools in minutes.

To start building with Swish, we recommend using the **Swish SDK**, Components and **Intents**.

> [!NOTE]
>
> **Install Swish from the Shopify App Store** \\
>
> Before continuing with this quickstart, make sure Swish is installed in your
> Shopify store.

The Swish SDK delivers a consistent, high-performance experience across different JavaScript environments. Whether you're building within a Shopify theme, using Hydrogen, or integrating custom storefronts, Swish makes it simple to add powerful shopping tools to your store.

> [tab] Liquid
>
> **1. Enable the app embed**
>
> Open the Shopify theme editor and enable the **Swish embed** block. The embed loads the SDK automatically and handles storefront credentials, customer context, and localization for you - no code required.
>
> 1. Go to **Online Store** > **Themes** > **Customize**.
> 2. Open **App embeds** (in the left sidebar).
> 3. Toggle **Swish embed** on and click **Save**.
>
> **2. Install the Swish snippet**
>
> Copy the [`swish.liquid`](https://swish.app/docs/references/sdk/elements#liquid-snippet) snippet into `snippets/` and the matching [`swish-theme.css`](https://swish.app/docs/references/sdk/elements#liquid-snippet) starter into `assets/`. Then render the snippet's init block in `theme.liquid` before `{{ content_for_header }}` - it sets `window.SwishOptions` and loads the stylesheet so the embed picks them up.
>
> ```liquid theme.liquid theme={null}
> {%- render 'swish' -%}
> {{ content_for_header }}
> ```
>
> **3. Add a save button on a product detail page**
>
> Let customers save and unsave products from any product detail page.
>
> > [tab] Snippet
> >
> > Render the save component anywhere on a product page. The snippet defaults to `context="pdp"` - the SDK reads the product from the current URL and reacts to SPA navigation.
> >
> > ```liquid theme={null}
> > {%- render 'swish', component: 'save', context: 'pdp' -%}
> > ```
> >
> > For product cards in a collection grid, pass `context: 'product-card'` and the SDK walks to the nearest product link instead.
> >
> > ```liquid theme={null}
> > {%- render 'swish', component: 'save', context: 'product-card' -%}
> > ```
> >
> > See the [elements reference](https://swish.app/docs/references/sdk/elements.md) for the full attribute set.
>
> > [tab] Placement
> >
> > Declare a placement in `SwishOptions` to target your product form and mount a save button automatically. Swish resolves the product from the page URL.
> >
> > ```js theme={null}
> > window.SwishOptions = {
> >   placements: [
> >     {
> >       id: "pdp-save-button",
> >       target: { selector: ".product-form" },
> >       mount: { mode: "after" },
> >       element: { name: "save-button" },
> >       layout: { type: "inline" },
> >     },
> >   ],
> > };
> > ```
> >
> > See [Product detail placement](https://swish.app/docs/guides/customize/placements/product-detail.md) for styling and layout options.
>
> **4. Add a home button**
>
> Give customers a way to access their saved items, notifications, and other Swish features.
>
> > [tab] Snippet
> >
> > Render the drawer component in your header. The default view is `home`; pass `view:` to open `saves`, `lists`, `orders`, `notifications`, or `profile` instead.
> >
> > ```liquid theme={null}
> > {%- render 'swish', component: 'drawer' -%}
> > ```
> >
> > See the [elements reference](https://swish.app/docs/references/sdk/elements.md) for the full attribute set.
>
> > [tab] Placement
> >
> > Declare a placement in `SwishOptions` to mount the home button in your store header. The button includes a built-in count badge.
> >
> > ```js theme={null}
> > window.SwishOptions = {
> >   placements: [
> >     {
> >       id: "header-header-button",
> >       target: { selector: ".header__icons" },
> >       mount: { mode: "prepend" },
> >       element: { name: "header-button" },
> >     },
> >   ],
> > };
> > ```
> >
> > See [Header placement](https://swish.app/docs/guides/customize/placements/header.md) for styling and customization options.
>
> **5. Customize (optional)**
>
> Two surfaces, two scopes:
>
> **`SwishOptions` configures the Swish app.** This is everything the SDK runs - the drawer UI, design tokens, intent options, translations, and so on. Edit it inside the `swish_init` capture in `snippets/swish.liquid`:
>
> ```liquid snippets/swish.liquid theme={null}
> {% capture swish_init %}
>   <script>
>     window.SwishOptions = {
>       ui: {
>         design: {
>           colors: {
>             primaryButtonBackgroundRgb: "0 0 0",
>           },
>         },
>       },
>     }
>   </script>
>   {{ 'swish-theme.css' | asset_url | stylesheet_tag: preload: true }}
> {% endcapture %}
> ```
>
> See the [configuration reference](https://swish.app/docs/references/sdk/configuration.md) for the full set of options.
>
> **`assets/swish-theme.css` styles the Liquid-rendered elements only.** Paste merchant button styles into the empty rule bodies - they target `<swish-save>` and `<swish-drawer>` and their children. This stylesheet does *not* affect the SDK-injected drawer UI; that's controlled by `SwishOptions.ui.design` (and `ui.css` if you need a full custom stylesheet for the app).
>
> > [accordion] Loading without the app embed
> >
> > If you cannot use the app embed, load the SDK manually in `theme.liquid`. You need to provide storefront credentials and customer context yourself.
> >
> > ```liquid theme.liquid theme={null}
> > <script>
> >   window.SwishOptions = {
> >     storefront: {
> >       storeDomain: {{ shop.permanent_domain | json }},
> >       accessToken: "YOUR_STOREFRONT_API_TOKEN",
> >     },
> >     context: {
> >       newCustomerAccounts: true,
> >       myshopifyDomain: {{ shop.permanent_domain | json }},
> >       shopName: {{ shop.name | replace: '&amp;', '&' | json }},
> >       moneyFormat: {{ shop.money_format | json }},
> >       customer: {
> >         id: {{ customer.id | json }},
> >         email: {{ customer.email | json }},
> >         firstName: {{ customer.first_name | json }},
> >         lastName: {{ customer.last_name | json }},
> >         b2b: {{ customer.b2b | json }},
> >       },
> >       localization: {
> >         country: {{ localization.country.iso_code | json }},
> >         language: {{ localization.language.iso_code | json }},
> >         market: {{ localization.market.id | json }},
> >       },
> >       routes: {
> >         accountUrl: {{ routes.account_url | json }},
> >         rootUrl: {{ routes.root_url | json }},
> >       },
> >     },
> >   };
> > </script>
> >
> > <script type="module">
> >   import { createSwish } from "https://swish.app/cdn/sdk@latest/swish.js";
> >
> >   await createSwish(window.SwishOptions);
> > </script>
> > ```
> >
> > Replace `YOUR_STOREFRONT_API_TOKEN` with your Shopify Storefront API access token. See the [configuration reference](https://swish.app/docs/references/sdk/configuration.md#storefront) for instructions on obtaining one.

> [tab] React
>
> **1. Install packages**
>
> ```bash npm theme={null}
> npm install @swishapp/react
> ```
>
> ```bash pnpm theme={null}
> pnpm add @swishapp/react
> ```
>
> ```bash yarn theme={null}
> yarn add @swishapp/react
> ```
>
> **2. Add SwishProvider**
>
> Wrap your app in `SwishProvider` so all child components can use Swish hooks.
>
> ```tsx theme={null}
> import { SwishProvider } from "@swishapp/react";
>
> function App() {
>   return (
>     <SwishProvider
>       options={{
>         storefront: {
>           storeDomain: "my-store.myshopify.com",
>           accessToken: "your-storefront-access-token",
>         },
>         context: {
>           customer: { id: customerId, email, firstName, lastName },
>           localization: { country: "US", language: "EN", market: "us" },
>           myshopifyDomain: "my-store.myshopify.com",
>           shopName: "My Store",
>           newCustomerAccounts: true,
>           routes: { accountUrl: "/account" },
>         },
>       }}
>     >
>       {/* Your app */}
>     </SwishProvider>
>   );
> }
> ```
>
> See the [Next.js](https://swish.app/docs/guides/headless/nextjs.md) or [Hydrogen](https://swish.app/docs/guides/headless/hydrogen.md) guide for a complete headless setup.
>
> **3. Add a save button**
>
> Use `useSwishItem` on a product detail page to let customers save and unsave products.
>
> ```tsx theme={null}
> import { useSwishItem } from "@swishapp/react";
>
> function SaveButton({ productId }: { productId: string }) {
>   const { saved, toggle, loading } = useSwishItem({ productId });
>
>   return (
>     <button type="button" onClick={toggle} disabled={loading}>
>       {saved ? "Saved" : "Save"}
>     </button>
>   );
> }
> ```
>
> **4. Add a home button**
>
> Give customers a way to access their saved items, notifications, and other Swish features. The `swish-intent` attribute works in React too - no hook needed.
>
> ```tsx theme={null}
> function SwishHomeButton() {
>   return (
>     <button type="button" swish-intent="view:home">
>       Swish Home
>     </button>
>   );
> }
> ```

## Direct API access

Swish provides a **Rest API** for advanced use cases where direct server-side or third-party integration is required.

> [!TIP]
>
> Use the direct API only when your project cannot run the SDK (e.g. on backend
> servers or native apps).

This API is primarily intended for:

* Third-party integrations - connecting Swish data to other systems or services.
* Server-side operations - running custom business logic or syncing data securely.
* Native mobile apps - integrating Swish features directly into iOS or Android applications.

Whenever possible, we recommend using the **Swish SDK**, which handles authentication, performance optimizations, and UI integration automatically. The SDK abstracts much of the complexity involved in communicating with the API, ensuring a faster and more reliable development experience.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.