Booking widget
Copy a snippet, paste it where you want the widget, and it shows the business’s free times. This page has everything you need to do that, and to fix it when it does not work.
The three snippets
Your own snippet, with the real business name in it, is in the dashboard under Website widget. Below, the business is shown as your-business. Swap in yours.
1. Script (use this one if you can)
The widget takes on your page’s font and text colour, and sits on your page’s background. Put the first line where the widget should appear. The second line can go anywhere on the page, once.
<div data-whensday="your-business"></div>
<script async src="https://whensday.xyz/embed/v1.js"></script>2. Iframe (for builders that will not run scripts)
The widget runs in a box of its own, so it cannot see your page. It uses the look saved in your dashboard and follows the visitor’s light or dark setting. The height is fixed at 620 px; change height if you need more room.
<iframe src="https://whensday.xyz/embed/frame/your-business" title="Book an appointment"
loading="lazy" style="width:100%;max-width:480px;height:620px;border:0"></iframe>3. Plain link (works anywhere)
Not a widget, just a link to the business’s booking page. Use it in an Instagram bio, an email signature or a site that allows nothing else.
<a href="https://whensday.xyz/s/your-business?src=widget">Book online</a>The four layouts
Set the layout with data-layout. The widget follows the width of the space it is in, not the screen. A week in a column narrower than 300 px draws itself as agenda.
week (the default)
For a booking page or a wide column. Pick a service, pick one of seven days, pick a time.
next
For sidebars, footers and contact pages. The next day with a free time, and its first three times.
agenda
For narrow columns. The next four open days stacked, three times each and a count of the rest.
button
For the whole site. A floating Book now button in the corner of the screen that opens the next layout. Only one floats per page. The example below is pinned inside its box so it does not float over this page.
Attributes
Put these on the div that has data-whensday. Everything is optional. Anything you leave out uses its default.
| Attribute | Values | Default | What it does |
|---|---|---|---|
data-layout | week | next | agenda | button | week | Which of the four layouts to draw. |
data-location | branch slug | the first branch | Preselects a branch, by the slug shown in its booking link. |
data-service | service id | none | Preselects a service, so the visitor goes straight to choosing a time. |
data-staff | staff id | any | Preselects a team member when the staff picker is turned on. |
data-scheme | auto | light | dark | auto | Pins light or dark, instead of detecting it from the page background. |
data-accentGrowing | #rrggbb | the text colour | The colour of the selected day, the selected time and the book button. |
data-textGrowing | #rrggbb | the host page's text colour | The main text colour, which muted text and borders are derived from. |
data-backgroundGrowing | #rrggbb | transparent | A solid background for the widget, instead of showing the page through it. |
data-radiusGrowing | 0 to 20 (px) | 10 | The corner radius of controls, in pixels; cards and the pill follow from it. |
data-fontGrowing | inherit | system-sans | system-serif | jost | inherit | The typeface, which is the host page's own unless you choose another. |
Rows marked Growing only apply on the Growing and Enterprise plans. On other plans the widget ignores them. The other attributes work on every plan. The colour and corner settings are explained in the styling guide.
The same business can appear twice on one site, set up differently. This one shows the next layout for one service at one branch, for a sidebar:
<div data-whensday="your-business" data-layout="next" data-location="sea-point" data-service="haircut"></div>
<script async src="https://whensday.xyz/embed/v1.js"></script>The branch is the slug in its booking link. The service is its id. If either is not found, the widget uses the business’s default instead of showing nothing.
Letting visitors choose who they see
By default the widget does not ask who the visitor wants to see. It shows every free time for the service and the business matches the booking with whoever is free, which suits most visitors: somebody booking a first visit does not know the names.
Where people book a person rather than a time, as at most barbers, turn the picker on. It is a setting, not part of the snippet: in the dashboard, open Website widget and switch on Let visitors choose who they see, then save. Every site the widget is on picks it up within about five minutes, with no change to the snippet. Visitors can still choose First available.
With the picker on, data-staff chooses who is selected when the widget opens, for example on a page about one barber. Its value is the id at the end of that person’s address in the dashboard, under Staff. With the picker off, data-staff is ignored and the widget shows first available, so a stale id never hides your times.
Install on your site
Every builder calls it something different. What you want is a block that lets you paste HTML. Start with snippet 1. If the widget does not appear, the builder is removing scripts, so use snippet 2.
WordPress
- Edit the page where the widget should go.
- Add a Custom HTML block where you want it. (In the older classic editor, use the Text tab instead of Visual.)
- Paste snippet 1 and update the page.
Some WordPress set-ups remove script tags from pages edited by people who are not administrators. If so, ask an administrator to paste it, or use snippet 2.
Wix
- Add an embed element for your own HTML code.
- Choose to paste code, and paste snippet 2.
Wix puts embedded code in a box of its own, so it cannot give the widget your site’s font. Snippet 2 is the one made for that.
Squarespace
- Edit the page and add a Code block where the widget should go.
- Paste snippet 1, and make sure the block runs the code instead of showing it as text.
Some Squarespace plans only allow HTML in a Code block, not scripts. If the widget does not appear, use snippet 2.
Shopify
- Open the theme editor on the page where the widget should go.
- Add a Custom Liquid or custom HTML block there.
- Paste snippet 1 and save.
Plain HTML
Paste snippet 1 into your page where the widget should go. If you want more than one widget on a page, add one div for each and keep a single script line.
Strict sites (Content Security Policy)
If your site sends a Content-Security-Policy header, add these. Without them the browser blocks the widget and says so in its console.
script-src https://whensday.xyz;
connect-src https://whensday.xyz;
frame-src https://whensday.xyz;script-srclets the page load/embed/v1.js.connect-srclets the script ask for the business’s details and free times.frame-srcis only needed for the iframe snippet.
The widget draws with constructed stylesheets, which a style-src rule does not apply to, and loads no images or fonts, so nothing else is needed. If your policy uses nonces, the script tag needs yours.
Single-page apps and late-loaded content
The script draws every [data-whensday] element that is on the page when it loads. Sites built with React, Vue or a page builder often add elements afterwards. For those, call Whensday.render(element, options) yourself, after the script has loaded.
<div id="booking"></div>
<script>
// Run this once the Whensday script (the second line of snippet 1) has loaded.
Whensday.render(document.getElementById('booking'), {
slug: 'your-business',
layout: 'next',
});
</script>If the element already carries data-whensday and any data-* attributes, you can pass just the element:
// The element already has data-whensday, so no slug is needed.
Whensday.render(element);The options are slug, layout, location, service, staff and scheme, with the same values as the attributes of the same names. Options win over attributes. Colours, corners and font are not options. Set them with attributes or custom properties, as described in the styling guide.
Calling render again on the same element redraws it. Whensday.version tells you which script you have.
Troubleshooting
Nothing appears
- The
data-whensdayvalue must be the business’s slug exactly as in its dashboard snippet. - The business must be published. If it is not, the widget shows a plain link, or only the Whensday name, instead of times.
- Open the browser console. A message about a blocked script or request means a Content Security Policy (see above) or an ad blocker.
- Your builder may be removing the script. Try snippet 2.
- If the page is cached, clear the cache. An old copy of the page will not have the snippet.
It looks unstyled, or does not match the site
- On snippet 1 the widget takes on the font and text colour of the element it sits in. If it looks plain, check that the parent has the font you expect.
- In an iframe (snippet 2) the widget cannot see your page and uses the saved look and the visitor’s light or dark setting.
- It sets its own text size in pixels. A page that makes its text bigger or smaller will not change it.
- Your own CSS cannot restyle what is inside it. Use the settings in the styling guide.
My colours are not applying
Colours, corner radius and font are part of the Growing and Enterprise plans. On other plans the widget ignores data-accent, data-text, data-background, data-radius, data-font and the matching --whensday-* properties, and stays neutral. Light and dark (data-scheme) and everything in the attributes table that is not marked Growing still work. If the plan has just changed, allow about five minutes for it to reach your site.
The floating button is hidden behind a cookie banner
This is on purpose. The button sits just below the highest layer a page can use, which is where cookie and consent banners sit. A banner the visitor has to answer is never covered by a booking button. It is there underneath, and shows as soon as the banner is answered or closed.
Versions
v1.jskeeps working. It is updated in place, and a fix reaches your site within about an hour without you changing anything.- The attribute and custom property names on this page are the contract. They will not be renamed or removed in
v1.js. - A change that would break an existing site ships as
v2.js, andv1.jsstays. - The JSON the widget fetches is internal. It is not an API, and it can change at any time. Do not call it yourself.
Want to try a look before you commit to it? Open the playground.