Options

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.

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:

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.

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.
• 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.
• 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.

Integrations

• ajaxApi (true): Smootify answers the Shopify AJAX API (/cart.js, /cart/add.js…) on the page. See Shopify AJAX API.
• structuredData (true): the product JSON-LD on product pages. See SEO and structured data.
• 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.
• 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.
• 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.

<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:

<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.

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.

The attributes Smootify writes on html, such as logged-in, are in CSS.

Where people get stuck