Voucher Widget Embedding

The voucher widget is a <giftcard-widget> web component that loads the APRO voucher shop for a single location in an iframe. Drop two lines into any page and customers can browse, buy and personalise gift cards without leaving the host site.

Script: https://smorderfrontend.azureedge.net/embed/widget.js
Tag: <giftcard-widget location-id="…">
Three modes: inline list (the voucher list fills its container), inline button (a button is rendered in the page flow and opens a panel), or floating button (a fixed FAB opens a panel)

Quick start

The minimum embed — load the script once, then add the tag wherever the shop should appear:

<script src="https://smorderfrontend.azureedge.net/embed/widget.js"></script>
<giftcard-widget location-id="535"></giftcard-widget>

That’s it. The widget queries the location’s voucher categories, renders the shop, and handles the customer flow through to checkout. The host page only needs to provide layout space.

Live sample — inline button

Rendered with presentation="inline-button". The trigger sits in the page flow exactly where the <giftcard-widget> tag is placed; clicking it opens the voucher shop in a modal panel.

<script src="https://smorderfrontend.azureedge.net/embed/widget.js"></script>
<giftcard-widget
  location-id="535"
  locale="en"
  presentation="inline-button"
  expand-icon="redeem"
  expand-label="Vouchers"
  headline="Buy a voucher"
  max-height="700"
></giftcard-widget>

Live sample — inline list

Same widget without presentation set — the full voucher list drops into the page flow up to a fixed max-height.

<script src="https://smorderfrontend.azureedge.net/embed/widget.js"></script>
<giftcard-widget
  location-id="535"
  locale="en"
  max-height="700"
></giftcard-widget>

Interactive builder

Tweak any attribute below — the markup updates instantly and the preview re-mounts the widget with the new configuration. Copy the final snippet straight into your CMS or template.

Configuration

Location & language

location-id · location Numeric APRO location ID — must exist on the chosen host. locale · language Passed to the voucher UI; also sets the floating button default label.

Mode & size

presentation · mode Inline drops the list into the page flow; expandable shows a floating button with a panel. max-height · height limit (px) Inline: iframe height. Expandable: maximum panel height (also bound to viewport). page-background · iframe page color Any CSS color. Applied to the iframe body inside the embed so the shop blends with the host page. Empty = the shop's default.

Button & panel

position · FAB & panel anchor Corner key, hyphenated; drives the FAB position and the edge the panel docks to. max-width · panel width (px) Applies only to the expandable panel (not to the inline iframe width). expand-label · button text Overrides the locale-dependent default on the floating button; leave empty for automatic. expand-theme · button look Dark or light styling of the floating button; expandable only. expand-icon · Material Icons glyph Material Icons ligature name (see Google Fonts Icons). No image URLs. headline · panel title Only expandable: bar above the iframe inside the panel; also passed as ?headline=…

Mobile behaviour

Open voucher editor in a new tab on mobile Sets breakoutPageOnMobile="true" so the personalized voucher editor can break out of the iframe on phones.

Markup

The HTML you paste into your page. Updates as you change fields above.

Ready.

Live preview

The widget below is rendered with the markup on the left.

Inline-button mode

The recommended default for most pages. Set presentation="inline-button" to render the trigger in the page flow exactly where the <giftcard-widget> tag is placed. Clicking it opens the voucher shop inside a modal panel. The host page’s layout stays untouched until the customer opts in.

<giftcard-widget
  location-id="535"
  locale="en"
  presentation="inline-button"
  expand-icon="redeem"
  expand-label="Vouchers"
  headline="Buy a voucher"
  max-height="700"
></giftcard-widget>

Floating-button mode

Set presentation="expandable" to switch to a fixed floating-action button: a circular pill in one of six corners opens a docked panel with the shop inside. Useful when you want a persistent entry point that follows the visitor down the page.

<giftcard-widget
  location-id="535"
  locale="en"
  presentation="expandable"
  position="right-bottom"
  max-height="700"
  max-width="420"
  expand-label="Gift cards"
  expand-icon="card_giftcard"
  headline="Buy a voucher"
></giftcard-widget>

position controls both the FAB anchor and which edge the panel docks to. Allowed values:

right-bottom (default), left-bottom, center-bottom
right-top, left-top, center-top

expand-icon is a Material Icons ligature name (e.g. redeem, card_giftcard, celebration). Bundled via @fontsource/material-icons inside the embed — image URLs are not supported.

expand-theme switches between dark (default) and light styling for the button. The panel header follows the same theme — dark in default mode, light when expand-theme="light".

Inline-list mode

Leave presentation empty (or omit it) to drop the voucher list itself into the page flow. The widget takes the width of its parent and grows to the iframe’s natural height, capped at max-height. Use this when you want a dedicated “Gift cards” landing section.

<giftcard-widget
  location-id="535"
  locale="en"
  max-height="700"
></giftcard-widget>

Attributes

Attribute	Required	Default	Description
`location-id`	✅	—	Numeric APRO location ID. The widget refuses to mount without it.
`locale`	—	`de`	UI language inside the iframe: `de`, `en`, `it`. Also picks the button’s default label.
`presentation`	—	“ (inline list)	`inline-button` renders a trigger in flow, `expandable` renders a fixed FAB. Empty or unknown = full inline list.
`max-height`	—	—	Pixel cap. Inline list: iframe height. Panel modes: panel height (also bounded by viewport).
`max-width`	—	—	Pixel cap for the panel width. Panel modes only.
`position`	—	`right-bottom`	One of six corner keys; controls the panel anchor (and FAB position when `presentation="expandable"`). Panel modes only.
`expand-label`	—	locale default	Text on the trigger button. Empty = automatic by `locale`. Panel modes only.
`expand-theme`	—	`dark`	`dark` or `light`. Applies to both the trigger and the panel header. Panel modes only.
`expand-icon`	—	—	Material Icons ligature shown left of the label. Panel modes only.
`headline`	—	—	Title bar above the iframe in the panel; also forwarded as `?headline=…` to the iframe. Panel modes only.
`page-background`	—	—	Any CSS color (`#ffffff`, `rgb(...)`, `transparent`, …). Applied to the iframe body so the embedded shop blends with the host page; also tints the panel and the inline iframe wrapper while the iframe loads.
`breakoutPageOnMobile`	—	`false`	When `true`, the personalised voucher editor opens in a new tab on phones instead of inside the iframe.

Loading the script

Load widget.js once per page — anywhere in <head> or before the closing </body>. It registers the <giftcard-widget> custom element globally; subsequent <giftcard-widget> tags on the same page activate automatically.

<script src="https://smorderfrontend.azureedge.net/embed/widget.js"></script>

Multiple widgets on one page are supported (e.g. an inline shop plus an expandable FAB elsewhere). Each iframe is isolated.