# Options

> Configure Smootify with the userOptions of the integration, grouped by task, plus the label globals and the cart animations.

Status: Ready (Smootify 2.0)  
URL: https://www.smootify.io/docs/astro/developers/options  
Updated: 2026-10-21

Smootify reads its settings from `window.SmootifyUserOptions`, an object that the integration writes into every page from its `userOptions`. This page groups the options by task and covers the other globals Smootify reads: labels and animations. The full list, with every default, is in the Reference under [Options](https://www.smootify.io/docs/astro/reference/options).

## Set the options

Set the options in `userOptions` of the Smootify integration, in `astro.config.mjs`. Only the options that differ from the defaults need to be there:

```js
smootify({
  siteId,
  userOptions: {
    newCustomerAccountsPublicKey: "your-client-id",
    productsBase: "product",
  },
});
```

- Smootify writes the object into every page, right before its script, and reads it once, when it starts. A change made later has no effect.
- The build reads the same object. Put there everything the first draw of the page depends on, such as the route bases and `useBrowserFormatter`: an option set in a script of your own is not seen by the build.
- With Astro’s `trailingSlash: "always"` the integration sets `trailingSlash: true`. Your own value in `userOptions` wins.

The integration is covered in [Install Smootify in Astro](https://www.smootify.io/docs/astro/start/install).

## Page addresses

Smootify builds links to products, collections and vendors from the folders of your pages, and needs the folder of the account pages.

- **`productsBase`** (default `"products"`), **`collectionsBase`** (`"collections"`), **`vendorsBase`** (`"vendors"`): the folders of your product, collection and vendor pages. If your pages use other names, set these to match: see [Install Smootify in Astro](https://www.smootify.io/docs/astro/start/install#4-options).
- **`accountBase`** (`"account"`): the folder of the account pages. A visitor who is not logged in is sent away from them.
- **`orderPageUrl`** (`"/account/order"`) and **`subscriptionPageUrl`** (`"/account/subscription"`): the pages that show one order and one subscription.

## Customer accounts

- **`newCustomerAccountsPublicKey`**: the client id of Shopify’s Customer Account API. Without it, login, the account elements and store credit do not work. See [Customer accounts](https://www.smootify.io/docs/astro/build/account).
- **`newCustomerLoginRedirect`**: where Shopify sends the customer back after login. The default is the site’s address.
- **`accountPageRedirectTo`**: where a visitor who is not logged in goes from an account page: an address (default `/`), or `"passwordless-login"` to start the login.

## Markets and prices

- **`selectMarketBasedOnBrowserLanguage`** (`false`): for a visitor with no saved country, the browser’s languages choose the market.
- **`useBrowserFormatter`** (`false`): prices formatted by the browser for the market (`Intl.NumberFormat`), instead of the store’s money format.

## Speed and cache

- **`preload`** (`true`): the browser prepares product, collection and vendor pages ahead, and product data is loaded early.
- **`cacheDuration`** (`0`): minutes a product stays in the browser’s cache. While `preload` is on, `0` becomes 10.
- **`prefetch`** (`true`): once the page is idle, the products of the links near the screen, hovered or touched are fetched into the cache, so the next product page renders from it. It needs the cache: it is off when `preload` is `false` and `cacheDuration` is `0`.
- **`gsap`** (`true`): Smootify loads GSAP when the page is idle, for the cart and panel animations, unless the page already loads it. `false` never loads it: the animations then use the browser’s own animation API.

More in [Performance](https://www.smootify.io/docs/astro/start/performance).

## Integrations

- **`ajaxApi`** (`true`): Smootify answers the Shopify AJAX API (`/cart.js`, `/cart/add.js`…) on the page. See [Shopify AJAX API](https://www.smootify.io/docs/astro/developers/ajax-api).
- **`structuredData`** (`true`): the product JSON-LD on product pages. See [SEO and structured data](https://www.smootify.io/docs/astro/start/seo).
- **`analytics`**: an object with the ids of the tracking pixels Smootify loads with the visitor’s consent: `metaPixelId`, `ga4MeasurementId`, `googleAdsId`, `tiktokPixelId`, and `waitForConsent` (`true`). See [Analytics and pixels](https://www.smootify.io/docs/astro/features/analytics).
- **`enableAutoTrack`** (`true`): product view, add to cart and checkout events for the GA4, Meta, Klaviyo and Mixpanel scripts the page loads itself, after consent.

## Labels

These globals replace texts Smootify writes. They are not in `userOptions`: set them on `window`, in an `is:inline` script in the `head` of `src/layouts/Base.astro`.

- **`window.SmootifyLabels`**: `{ calculatedAtCheckout: "…" }`, the text of the taxes and duties in the cart when a line has a custom price. Read once, at start.
- **`window.SmootifyStatusLabels`**: the texts of order and subscription statuses, keyed by Shopify’s value (`PAID`, `FULFILLED`…). A status without a text shows Shopify’s value.
- **`window.SmootifySortLabels`**: the texts of the sort options, keyed by `relevance`, `price_asc`, `price_desc`, `best_selling`, `created_asc`, `created_dsc`, `title_asc` and `title_dsc`. Which list shows each one: [Sort labels](https://www.smootify.io/docs/astro/build/filters#sort-labels).
- **`window.SmootifyStoreCreditEventsLabel`**: the texts of store credit events, keyed by `ADJUSTMENT`, `ORDER_CANCELLATION`, `ORDER_PAYMENT`, `ORDER_REFUND`, `PAYMENT_FAILURE`, `PAYMENT_RETURNED`, `RECURRING_PAYMENT` (“Subscription Payment”) and `TAX_FINALIZATION`.

```astro
<script is:inline>
  window.SmootifySortLabels = { price_asc: "Price, low to high", price_desc: "Price, high to low" };
  window.SmootifyStatusLabels = { PAID: "Paid", FULFILLED: "Shipped" };
</script>
```

The last three are read each time they are used, so they can also be set later.

## Cart and panel animations

The mini cart and `modal-backdrop` panels open and close with an animation you can change:

- **`window.cartInAnimation`** and **`window.cartOutAnimation`**, with **`window.cartInAnimationSettings`** and **`window.cartOutAnimationSettings`**;
- **`window.detailInAnimation`** and **`window.detailOutAnimation`**, with their `…Settings`, for `modal-backdrop`.

An animation is `{ prop: [from, to] }` or `{ from: {}, to: {} }`; the settings hold `duration` (seconds) and `easing` (a name or a cubic-bezier list).

Set them in an inline script in the head of your layout, so that they are there before Smootify starts:

```astro
<script is:inline>
  window.cartInAnimation = { opacity: [0, 1], x: ["100%", "0%"] };
  window.cartInAnimationSettings = { duration: 0.4, easing: [0.25, 0.46, 0.45, 0.94] };
</script>
```

A cart inside a popover is not animated: it keeps the transitions it was designed with. See [Popovers](https://www.smootify.io/docs/astro/build/popovers).

## The html element

Smootify also reads attributes on the page’s `html` element:

- `lang`: the page’s language, and the first market. Set it on every page, such as `<html lang="en">`;
- `data-smootify-404`: marks the 404 page, so that Smootify looks the address up in the store’s URL redirects. The integration writes it on the built 404 page; a 404 page rendered on demand takes it from `smootify404Attrs`. See [Shopify Collabs](https://www.smootify.io/docs/astro/features/shopify-collabs#4-the-404-page).

The attributes Smootify writes on `html`, such as `logged-in`, are in [CSS](https://www.smootify.io/docs/astro/developers/css).

## Where people get stuck

> [!STUCK]
> - **An option has no effect.** Its name is wrong, or a script of your own sets it after Smootify started. Set it in `userOptions` of the integration.
> - **Product links lead to a 404.** The folders of your pages are not the default ones (`products`, `collections`, `vendors`). Set `productsBase`, `collectionsBase` and `vendorsBase` in `userOptions`.
> - **Login does nothing and the account elements stay empty.** `newCustomerAccountsPublicKey` is missing.
> - **Products never come from the cache.** `preload` is `false` and `cacheDuration` is `0`, which also turns `prefetch` off.