# Elements reference

> ShopFast(), elements(), every element and its options, element and group methods, and confirmPayment().

Source: https://shopfa.st/docs/elements/reference

Types for all of this are in [shopfast-elements.d.ts](https://shopfa.st/docs/elements/shopfast-elements.d.ts). Save it next to your code
and reference it with `/// <reference path="shopfast-elements.d.ts" />`, or copy the parts you use.

## ShopFast()

```js
const shopfast = ShopFast({ store: "https://lumenfold.shopfa.st", nonce: "r4nd0m", debug: false });
```

| Option | What it does |
| --- | --- |
| `store` | Your store's address. Leave it out when the script loads from your store. A custom domain works too. |
| `nonce` | Your CSP nonce. Put on every frame and style tag the script adds. See [Content Security Policy](https://shopfa.st/docs/elements/security#content-security-policy). |
| `debug` | Logs every event to the console while you build. |

`ShopFast("https://lumenfold.shopfa.st")` works too. `shopfast.version` is the script's version.

## shopfast.elements()

One shared cart and the elements that show it. Make one per checkout on the page.

```js
const elements = shopfast.elements({
  items: [
    { product: "northwind-sans", variant: "var_9zp0phmv1xa45v7g97wv", quantity: 1 },
    { product: "studio-notion-templates", amount: "12.00" },
  ],
  brand: { mode: "light", tokens: { accent: "#b2452a" } },
  locale: "de",
  returnUrl: "https://yourshop.com/thanks",
});
```

| Option | What it does |
| --- | --- |
| `items` | What starts in the cart, up to 20 lines. `product` is a handle or a `prd_` id; `variant` an option's `var_` id (the first available option when left out); `quantity` 1 to 100; `amount` the price for pay what you want products, as the buyer would type it. Leave it empty to let `product` and `buyButton` elements fill the cart. |
| `brand` | `mode`, `preset`, `tokens`, `fonts` and `rules`. See [Styling](https://shopfa.st/docs/elements/styling). |
| `locale` | Language and number format, like `de` or `fr-CA`. Built-in words come in English, German, French and Spanish; prices format for any locale. Defaults to your page's `lang`. |
| `strings` | Replace any built-in word by key, like `{ addToCart: "Get it" }`. Your checkout's own words (pay button, headings, terms) come from **Storefront → Checkout**. |
| `returnUrl` | Where a gateway that takes over the whole tab sends the buyer back to. See [Taking payment](https://shopfa.st/docs/elements/payments). |
| `currency` | The store always charges in its own currency. If you pass a different one, a `trace` says which one is used. |

## elements.create()

`elements.create(type, options)` returns an element. Nothing shows until you `mount` it.

### checkout

Everything in one element.

| Option | Default | What it does |
| --- | --- | --- |
| `showSummary` | `true` | The cart lines and add-ons above the form. `false` shows just the total. |
| `title` | none | A title row with "Secure checkout". The overlay checkout uses your store's name here. |

### summary

| Option | Default | What it does |
| --- | --- | --- |
| `editable` | `true` | Quantity steppers and remove. `false` shows quantities only. |
| `showOffers` | `true` | Order bumps and upsells under the lines. |
| `showCodes` | `false` | A code field inside the summary, for layouts without a `coupon` element. |
| `showProgress` | `true` | The reward bar ("$6.00 to go: free bonus pack"), when your store has one. |

### email

| Option | Default | What it does |
| --- | --- | --- |
| `label` | "Email" | The field's label. |
| `placeholder` | "you@example.com" | The field's placeholder. |

When Fraud Shield asks the buyer to confirm their email, the 6-digit code box opens in this element.

### payment

| Option | Default | What it does |
| --- | --- | --- |
| `layout` | `list` | `grid` puts the ways to pay side by side. |

Shows the store's ways to pay for the buyer's country and order total (your rules and order limits apply, with the
reason when one is not offered). In test mode the selected way shows the test card and the test outcomes.

### coupon

| Option | Default | What it does |
| --- | --- | --- |
| `collapsed` | `false` | Starts as a "Have a code?" link. |

Takes discount codes and gift card codes in one field. Applied codes show as chips with a remove button.

### consent

| Option | Default | What it does |
| --- | --- | --- |
| `showSeller` | `true` | "Sold by", with your legal details from **Settings → General**. |

Shows your terms checkbox, the marketing opt-in when you turned it on, and the EU and UK immediate delivery box for
buyers who need it, with the same sentence and rules as your own checkout.

### billingAddress

No options. Shows name, country, phone and address as **Storefront → Checkout → Fields** asks for them. When every
field is hidden it draws nothing.

### customFields

No options. Your checkout questions and the questions of the products in the cart.

### payButton

No options. The pay button with the total (or "Confirm and continue" while an email code is pending), your secure
checkout note and trust badges. Alone on the page, without a `checkout` or `payment` element, it also shows the
messages the buyer needs and the paid state.

### product

| Option | Default | What it does |
| --- | --- | --- |
| `product` | required | A handle or `prd_` id. |
| `variant` | first available | The option picked at first. |
| `layout` | `card` | `compact` or `row`. |
| `showDescription` | `true` | The short description. |
| `showQuantity` | `false` | A quantity stepper; quantity prices update as it changes. |
| `showTiers` | `true` | Quantity prices ("Buy 5+ · save 20%"). |
| `action` | `add` | `buy` adds the product and opens the checkout overlay. |
| `text` | "Add to cart" | The button label. |

### buyButton

| Option | Default | What it does |
| --- | --- | --- |
| `product` | required | A handle or `prd_` id. |
| `variant`, `quantity` | | What it adds. Nothing is added twice: a product already in the cart just opens the overlay. |
| `text` | "Buy now" | The label. |
| `showPrice` | `true` | The price after the label. |
| `size` | `md` | `sm`, `md` or `lg`. |
| `block` | `false` | Full width. |

### cartButton

| Option | Default | What it does |
| --- | --- | --- |
| `text` | "Cart" | The label. |
| `showTotal` | `false` | The total next to the count. |
| `size`, `block` | | As for `buyButton`. |

### tip and offers

`tip` shows your tip amounts (Storefront → Checkout → Tips) and draws nothing when your store takes none. `offers`
shows order bumps, upsells and the reward bar; pass `title` to give it a heading.

## Element methods

| Method | What it does |
| --- | --- |
| `mount(target)` | Put the element in the page: a CSS selector or an element. |
| `update(options)` | Change its options without remounting. |
| `focus()` | Focus its first field. |
| `unmount()` | Take it out of the page; `mount` puts it back with the same cart. |
| `destroy()` | Remove it for good. |
| `on(event, handler)` | Listen to this element's own `ready`, `change`, `focus`, `blur`, `resize` and `loaderror`. |

## Group methods

| Method | What it does |
| --- | --- |
| `on(event, handler)` | Listen to an event from any element, or to all of them with `'*'`. Returns a function that stops listening. Handlers get `(data, eventName)`. |
| `once(event, handler)` | Listen once. |
| `off(event, handler)` | Stop listening. |
| `update({ brand, items, locale, strings, returnUrl })` | Restyle, re-word or replace the cart in place. No remount, no flash. |
| `addItem(item)` | Put products in the cart from your own buttons. Takes one item or a list. |
| `edit()` | Unlock the form after a payment was started, to fix a typo or pick another way to pay. |
| `open()`, `close()` | Open or close the checkout overlay the buy and cart buttons use. |
| `getElement(type)` | The first element of a type, or `null`. |
| `destroy()` | Remove every frame and listener. |

## shopfast.confirmPayment()

Pay from your own button instead of the `payButton` or `checkout` element:

```js
payButton.addEventListener("click", async () => {
  const result = await shopfast.confirmPayment({ elements, returnUrl: "https://yourshop.com/thanks" });
  if (result.error) showMessage(result.error.message);
  else showThanks(result.order.number);
});
```

It resolves once the order is paid (`{ order }`) or the payment stopped (`{ error }`). Call it from the click itself:
some gateways need their own window, and browsers only let a page open one during a click. Details in
[Taking payment](https://shopfa.st/docs/elements/payments).