JavaScript API reference

The GiftPrint Storefront widget exposes a JavaScript API on window.GiftPrintWidget for theme developers who want to build custom UIs or integrate gift notes with their storefront.

The API is available on any product page where the GiftPrint Gift Note Widget block has been added to the theme. All methods are no-ops if the widget is not present or disabled.

For setup instructions, see Storefront widget overview.

window.GiftPrintWidget.setMessage(text)

Set the gift message text programmatically. Updates the textarea, the live preview, the character counter, and the hidden cart properties, then dispatches giftprint:change.

window.GiftPrintWidget.setMessage("Happy Birthday to you!");

Parameters:

• text (string) — The gift message. The widget does not truncate or validate length — read getConfig().charLimit if you need to enforce a maximum yourself.

Returns: void

Use this to pre-fill the message from a URL parameter, external form, or custom UI element.

window.GiftPrintWidget.setTemplate(id)

Switch to a specific template design.

window.GiftPrintWidget.setTemplate("luxury");

Parameters:

• id (string) — Template ID. Valid values:
  • Style: minimal, botanical, luxury, playful
  • Occasion: holiday, birthday, thank-you, wedding, congratulations, baby-shower, sympathy

Returns: void

Invalid IDs are silently ignored. Use getConfig() to retrieve available template options.

window.GiftPrintWidget.setRecipient(name)

Set the recipient ("To") name shown above the message in the preview and submitted to the cart as properties[To].

window.GiftPrintWidget.setRecipient("Sara");

Parameters:

• name (string) — Recipient name. Pass an empty string (or null) to clear.

Returns: void

Updates the input field, the live preview, the hidden cart properties, and dispatches giftprint:change.

window.GiftPrintWidget.setSender(name)

Set the sender ("From") name shown below the message in the preview and submitted to the cart as properties[From].

window.GiftPrintWidget.setSender("Alex");

Parameters:

• name (string) — Sender name. Pass an empty string (or null) to clear.

Returns: void

Updates the input field, the live preview, the hidden cart properties, and dispatches giftprint:change.

window.GiftPrintWidget.getState()

Get the current widget state.

const state = window.GiftPrintWidget.getState();
console.log(state);
// {
//   enabled: true,
//   template: "luxury",
//   message: "Happy Birthday!",
//   to: "Sara",
//   from: "Alex"
// }

Returns: { enabled: boolean; template: string; message: string; to: string; from: string }

to and from are the recipient and sender name fields rendered alongside the message. They are sent to the cart as properties[To] and properties[From] when the widget is enabled.

Use this to read the current selections before adding to cart.

window.GiftPrintWidget.getConfig()

Get the widget configuration from the shop metafield.

const config = window.GiftPrintWidget.getConfig();
// {
//   charLimit: 500,
//   optimalCharLimit: 120,
//   templates: ["minimal", "botanical", ...],
//   defaultTemplate: "luxury"
// }

Returns:

{
  charLimit: number;
  optimalCharLimit: number;
  templates: string[];
  defaultTemplate: string;
}

• charLimit — hard character limit for the current page format
• optimalCharLimit — soft recommendation (widget shows warning at this length)
• templates — list of available template IDs
• defaultTemplate — shop's default template choice

window.GiftPrintWidget.enable()

Programmatically check the toggle: shows the message/preview content, re-enables the textarea, and re-injects the hidden cart properties so the gift note submits with the form. Equivalent to the customer ticking "Add a gift note".

window.GiftPrintWidget.enable();

Returns: void

window.GiftPrintWidget.disable()

Programmatically uncheck the toggle: hides the message/preview content panel and disables the message textarea. The widget then re-runs its form sync, which removes the dynamically injected properties[Gift Message], properties[To], properties[From], and properties[_has_gift_note] inputs. Equivalent to the customer un-ticking "Add a gift note".

window.GiftPrintWidget.disable();

Returns: void

Caveat: the static hidden <input type="hidden" name="properties[Template]"> lives in the markup unconditionally and is not removed by disable(). If your theme submits the product form while the widget is disabled, a Template property may still ride along; the rest of the gift-note properties will not.

If you want to keep the gift note submitting while running a fully custom UI, use destroy() instead — it forces the toggle on and only hides the chrome.

window.GiftPrintWidget.destroy()

Strips the visible widget chrome (toggle row, header, content panel) and zeros the widget's outer padding, border, background, and margin. Then forces the toggle into the "on" state (checkbox.checked = true, checkbox.type = "hidden"), so the gift note properties always submit with the form.

window.GiftPrintWidget.destroy();

Returns: void

Stronger and one-way compared to disable(). Once you call destroy():

• the default UI is gone from the layout
• the form keeps submitting properties[Gift Message], properties[Template], properties[To], properties[From]
• enable() / disable() will no longer change visibility (the elements have inline display: none and the toggle is hidden)

Use this when you replace the widget with your own UI and drive submissions with setMessage() / setTemplate().

Examples

Pre-fill message from URL parameter

const params = new URLSearchParams(window.location.search);
const message = params.get("gift_message");
if (message) {
  window.GiftPrintWidget.setMessage(message);
}

Lock template to a specific design

// Force all gift notes to use the "luxury" template,
// regardless of the shop's default template setting
window.GiftPrintWidget.setTemplate("luxury");

// Optional: hide the template picker
document.querySelectorAll(".giftprint-widget__thumbs").forEach((el) => {
  (el as HTMLElement).style.display = "none";
});

Build a completely custom UI

Use destroy() (not disable()) when replacing the widget — disable() removes the cart properties, so the gift note would not submit. destroy() hides the chrome but keeps the toggle on.

// Hide all default widget UI but keep the gift note submitting
window.GiftPrintWidget.destroy();

// Render your own template picker, message input, etc.
// and drive them via the API:

document.getElementById("custom-template-select").addEventListener("change", (e) => {
  window.GiftPrintWidget.setTemplate((e.target as HTMLSelectElement).value);
});

document.getElementById("custom-message-input").addEventListener("input", (e) => {
  window.GiftPrintWidget.setMessage((e.target as HTMLInputElement).value);
});

Events

The widget dispatches and listens for CustomEvents on document:

// Listen for state changes
document.addEventListener("giftprint:change", (e) => {
  console.log(e.detail); // { enabled, template, message, to, from }
});

// Inject a message from outside the widget
document.dispatchEvent(
  new CustomEvent("giftprint:set-message", { detail: { message: "Hello!" } })
);

There is no giftprint:ready event. The widget initializes synchronously after DOMContentLoaded and re-tries until window.GiftPrintWidget exists; if you need a guard, poll for window.GiftPrintWidget before calling its methods.

CSS styling

The widget can be styled via CSS custom properties and class names. Hidden form inputs (added to cart) always use the selected template and message, regardless of UI visibility.

See CSS variables for customization options.