Widgets and theming

This article covers everything about the widget you set up in the console: installing it, the allowed origins, test and live widgets, theming, and the hosted page. A widget is the quoting form on your page. It has a key, a list of sites it answers, one or more configurations behind it, and a look.

Before you begin

• At least one published configuration. See Your first configuration.
• Access to a page on your site where you can paste HTML.

Install it

1. In the console, open Widgets and create a widget, or open an existing one.
2. Attach the configurations it should offer.
3. Copy the snippet from the Put it on your website card in the widget editor and paste it where the quoting form should appear. It looks like this:

<script async src="https://cdn.quotometry.example/widget/v1/loader.js"></script>
<quotometry-quote widget="wgt_live_yourshop"></quotometry-quote>

The first line is a small loader that downloads the real widget only when a quoting form is actually on the page. Paste it in a Custom HTML block, a code embed or your template: anywhere you can put HTML. The developer documentation covers frameworks and site builders.

Allowed origins: the one thing you must get right

A widget answers only the sites you list. Put your site’s address in Allowed origins: the scheme and the host, like https://yourshop.com, with no path. If you also use www., list both, because a browser treats them as different origins. *.yourshop.com covers every sub-domain.

This is what stops somebody copying your key onto their own site and using up your quota. It is also the most common cause of “the widget shows an error”: see Troubleshooting.

Test widgets and live widgets

A test widget prices from the same configuration but never uses your quota and never creates a real order. It also works on localhost, so you can try it before you list any origin. A live widget does both.

A new widget starts in test mode. When it works, Go live turns it into the live widget with everything you set up: it gets a new wgt_live_… key, and the test key stops working. For a staging site that stays on test, keep a separate test widget.

Theming

Set colours, corner radius, density and the rest on the widget’s Look tab, with a live preview in light and dark.

Out of the box the widget is neutral: an amber highlight on the part and options the buyer picked, and a dark main button. Set a primary colour and it takes over both, in either scheme. The contrast table under the colours tells you if a label or a highlighted name would be hard to read, including in the dark scheme.

The widget uses its own typeface (Inter). To use your page’s font instead, set --quotometry-font: inherit on the element in your stylesheet.

If you prefer to control the look from your own stylesheet, set the --quotometry-* properties on the element and they win over the console. The widget reference lists them all.

Because the widget runs inside a shadow root, your stylesheet cannot break it by accident and its stylesheet cannot leak into your site. That is by design, and it is why theming uses variables rather than class names.

No website?

On the widget’s Hosted page and domain tab, switch on the hosted quoting page. You get a full quoting page with your logo and colours, at a link you can put in an e-mail signature, a social post or a QR code on the shop door, and on your own domain if your plan includes one. Plenty of shops run entirely this way.

When a buyer is not ready to order

The widget’s top bar offers Save quote. The buyer gets a link back to exactly the quote they configured: they can copy it, have it e-mailed to themselves, or download the PDF. Nothing is ordered, and the quote appears in your Inbox marked saved: a lead with a price already on it.

The link is read-only: nobody can order from it. If the buyer asked for it by e-mail, we send it to them and not to you, because the address was given for that one message. Once you have their address another way, send them the saved quote from the Inbox in the usual way: that link is the one that takes the order.

Several configurations behind one widget

Attach more than one configuration and the buyer chooses between them. With Offer a comparison across technologies switched on, the widget also prices the buyer’s part in every attached technology side by side. That is useful when the same part could sensibly be made two ways and you would rather the buyer saw the trade-off than guessed.

Choose the widget version

By default a widget loads the latest version of the widget code, which moves to each new release as Quotometry publishes it. On the widget’s settings you can pin a Widget version instead, to keep exactly what you have tested until you choose to move. The code on your page stays the same either way.

Next steps

• Troubleshooting: origin errors and content security policy.
• Orders and notifications: where quotes and orders arrive.
• Embedding: the widget in frameworks and site builders.