> ## Documentation Index > Fetch the complete documentation index at: https://quickbutik.dev/llms.txt > Use this file to discover all available pages before exploring further. # Web components setup > Use the kit's headless custom elements in any stack: with a bundler (Vite, Astro, Vue, Svelte, Nuxt) or with one script tag and no build step. `@quickbutik/kit/elements` is the same headless composition as the [React layer](/kit/react/setup), as custom elements: ``, ``, `` and friends. Use it for anything that is not React: a plain HTML page, Astro, Vue, Svelte, Nuxt, a Rails, Laravel or WordPress view, Webflow, an existing jQuery theme. * **Light DOM, no shadow root.** Your stylesheet reaches everything. * **No markup of their own.** The elements bind data into markup *you* wrote, through `data-qb-*` attributes, and reflect their state as attributes for your CSS. Four deliberate exceptions: `` renders an ``, `` writes its number, `` writes into ``, and `` renders the checkout's iframe. * **No CSS shipped.** The elements reflect their state as attributes for your own stylesheet. Do not mix the React layer and the elements on one page. Each brings its own cart store, and the two would not update together. ## Choose a setup One ` Varukorg () ``` * **Pin the version** in the URL and cache-bust on upgrade. * Use `defer`. The elements cope with being upgraded mid-parse either way; `defer` keeps the script off the critical path. * One self-contained file, no runtime dependencies, exposed as `window.Quickbutik`. Every attribute and the `window.Quickbutik` API are in [Scripting](/kit/web-components/scripting) and the [script tag reference](/kit/reference/script-tag). ```bash theme={null} npm install @quickbutik/kit ``` ```ts src/shop.ts theme={null} // Browser-only module: see "Import it only in the browser" below. import { configure, defineElements } from "@quickbutik/kit/elements" configure({ publishableKey: import.meta.env.VITE_QUICKBUTIK_PUBLISHABLE_KEY, currency: "SEK", locale: "sv-SE", }) defineElements() ``` `configure()` takes every [`createShopkitClient`](/kit/reference/client) option plus `locale` (and `consent` / `analytics` options for the [cookie banner](#consent-and-analytics)), and returns `{ client, cartStore }`. `defineElements()` registers the tags; it is explicit (not an import side effect) so the entry stays tree-shakeable, and idempotent, so calling it twice or after the script tag already did is harmless. ```ts theme={null} defineElements({ prefix: "shop-" }) // , for a tag-name collision defineElements({ warnOnUnhandledActions: false }) // silence the typo warning for data-qb-action ``` **Call `configure()` once, at startup.** A second call replaces the ambient client and cart store only for elements mounted afterwards; elements already on the page keep the first ones, so a badge and a drawer stop updating together. Never call it per client-side navigation. ## Import it only in the browser `@quickbutik/kit/elements` defines classes that extend `HTMLElement` when it loads. Importing it in Node (an SSR entry, a frontmatter, a server file) throws `ReferenceError: HTMLElement is not defined`. The root entry `@quickbutik/kit` is the server-safe one; use it for server-side reads. ```astro Astro theme={null} --- // Frontmatter runs on the server: use the plain client here, never /elements. import { createShopkitClient } from "@quickbutik/kit" const shopkit = createShopkitClient({ publishableKey: import.meta.env.PUBLIC_QUICKBUTIK_PUBLISHABLE_KEY }) const { data: products } = await shopkit.products.list({ limit: 12 }) --- ``` ```vue Vue theme={null} ``` ```svelte Svelte / SvelteKit theme={null} ``` ```ts Nuxt (plugins/quickbutik.client.ts) theme={null} // The .client.ts suffix keeps this plugin out of the server bundle. import { configure, defineElements } from "@quickbutik/kit/elements" export default defineNuxtPlugin(() => { configure({ publishableKey: useRuntimeConfig().public.quickbutikKey, currency: "SEK" }) defineElements() }) ``` Tell your framework's template compiler that `qb-*` tags are custom elements, so it does not try to resolve them as components (Vue: `compilerOptions.isCustomElement = (tag) => tag.startsWith("qb-")`). For pages that must be indexable, render the catalog HTML on the server with the plain client and use the elements for the interactive parts (cart, variant picker, checkout). See [Server-side rendering](/kit/vanilla/server-side). ## The ambient shop: there is no wrapper element The shop is **ambient**: one client and one shared cart store per page, set up once by `configure()` or by the script tag's `data-publishable-key`. Every element finds it on its own. An element that talks to the API and finds no shop reports a named `ShopkitConfigError` listing the three ways to provide one, sets `state="error"` and emits `qb:error`. ### ``: optional overrides `` exists for the cases a page-wide singleton cannot serve. A `` ancestor wins for its own subtree; everything else keeps using the ambient shop. ```html theme={null} … … … … ``` | Attribute / property | | | - | - | | `publishable-key` | The shop's `qb_pk_…` | | `api-url`, `checkout-url` | Only for a preview environment or a proxied checkout | | `image-base-url` | Fallback image base; rarely needed | | `currency` | The currency the subtree browses in. Changing it later switches that client without rebuilding it or its cart. See [Currencies](/kit/concepts/currencies) | | `locale` | Number formatting for that subtree | | `consent="false"`, `analytics="false"` | Turn consent, or only analytics, off for that subtree. A `` for the same shop as the page reuses the page's consent store and analytics hub | | `storage-key-prefix` | Run two shops in one browser | | `storefront-id` | Bind the subtree to a [campaign storefront](/kit/concepts/campaign-storefronts). Changing it builds a new client and cart store | | `.client` | A prebuilt client; wins over every attribute | | `.initialCart` | A cart read on the server, so the first paint shows the real basket | | `.cartStore` | The subtree's shared cart store | It emits `qb:shop-ready` with `{ client, cartStore, currency, locale }`. ## Set the currency Products and carts state the currency their prices are in (`product.currency`, `cart.currency`), and the elements format with it. For a shop that sells in its own currency only, nothing needs configuring. `currency` in `configure()` (or `data-currency` on the script tag) is the currency the page **browses in**: it is sent with every product, cart and checkout request, and a shop that offers that currency answers with converted prices. Leave it out to start in the shop's own currency. It doubles as the formatting fallback for a platform older than `product.currency`. ```ts theme={null} configure({ publishableKey, currency: "EUR", locale: "sv-SE" }) ``` ```html theme={null} ``` For a shop that offers several currencies, drop in a switcher. A choice reprices every product, list and cart on the page (the same cart, re-read) and is remembered for the next visit, winning over the configured value: ```html theme={null} ``` Display versus charge currencies, `setCurrency()` and the switcher's templates are covered in [Currencies](/kit/concepts/currencies). ## Consent and analytics **On by default.** A page configured by `configure()`, `` or the script tag gets the kit's default cookie banner appended to `` (unless it places its own ``), and loads the merchant's own GA4, GTM and Meta pixel from the shop's settings **only after the shopper agrees**. The elements report `view_item`, `search`, the cart events and the purchase, and every checkout handoff forwards the shopper's decision to the hosted checkout. ```ts theme={null} configure({ publishableKey, consent: { lang: "sv", privacyPolicyUrl: "/integritetspolicy" } }) configure({ publishableKey, analytics: false }) // the banner, but no pixels configure({ publishableKey, consent: false }) // no banner, no analytics ``` ```html theme={null} ``` Your own banner markup, gated content and every option: [Consent and analytics](/kit/concepts/consent-and-analytics). ## Next steps Bindings, repeats, actions and styling on state. Catalog, product page, cart, checkout and thank-you page. `window.Quickbutik`, events and recipes. Every element's attributes, scope, reflected state and events. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.