# Slot Picker

The Slot Picker Element is an embeddable interface for visualizing real-time availability. It converts an [Availability query](/developers/api/scheduling/availability/index.md)
into a list of bookable slots.

When a user confirms a slot, the Element passes that slot's details into a
callback function (provided when the Element is initialized).

### Demo
*(Interactive UI element — see the HTML version for the live demo)*

### Example initialization
```html
<div id="cronofy-slot-picker"></div>
<script src="https://elements.cronofy.com/js/CronofyElements.v1.67.6.js"></script>
<script>
    CronofyElements.SlotPicker({
        element_token: "{ELEMENT_TOKEN}",
        target_id: "cronofy-slot-picker",
        availability_query: {
            participants: [
                {
                    required: "all",
                    members: [
                        { sub: "acc_5ba21743f408617d1269ea1e" },
                        { sub: "acc_64b17d868090ea21640c914c" }
                    ]
                }
            ],
            required_duration: { minutes: 30 },
            query_periods: [
                { start: "2026-04-17T09:00:00Z", end: "2026-04-17T17:00:00Z" },
                { start: "2026-04-18T09:00:00Z", end: "2026-04-18T17:00:00Z" }
            ]
        },
        styles: {
            prefix: "custom-name"
        },
        callback: notification => console.log("callback", notification)
    });
</script>
```

### Element permissions
`availability` is required when generating the [Element Token](/developers/ui-elements/authentication/index.md).

### Element options
##### `element_token` *(required)*

The [Element Token](/developers/ui-elements/authentication/index.md) the
Slot Picker will use to communicate with Cronofy.

*Not required if the Element is activated in demo mode.*

##### `target_id` *(required)*

The ID of the DOM node the Element will be loaded in to.

##### `availability_query` *(required)*

Object that matches a valid Cronofy [Availability request](/developers/api/scheduling/availability/index.md).

> **INFO:** **Using the Slot Picker with Bookable Events**

It is possible to use the Slot Picker to display [Bookable Events](/developers/api/scheduling/bookable-events/index.md). To do so, use a [Bookable Events availability query](/developers/api/scheduling/bookable-events/availability/index.md) in place of a standard query.

You will also need to add a `bookable_event_ids` value when [creating your Element Token](/developers/ui-elements/authentication/index.md).

*Note that if the event IDs provided are not found, then the Slot Picker will load in an error state (showing the "There was an error loading the element" message to users). Event IDs may not be found either because the events do not exist or because the Slot Picker element token does not have the correct permissions to view the events.*

> **INFO:** **Using response_format**

The default behaviour will use `response_format: &quot;overlapping_slots&quot;` to allow slots to overlap. You may provide `response_format: &quot;slots&quot;`  to prevent this. Other `response_format` options are invalid when using the Slot Picker Element.

##### `callback` *(required)*

The function to be called when an action has occurred within the Element. Receives an object in the format:

```json
{
    "notification": {
        "type": "notification_type"
    }
}
```

The object will always include a `notification` object with a `type` attribute to allow you to determine how to handle it. Your application should ignore notifications it does not understand as new ones may be added in the future.

###### slot_selected
Sent by the Element when in the `confirm` mode after the user has confirmed
their selection, and straight away when the slot is selected in `no_confirm`
mode.

```js
{
    "notification": {
        "type": "slot_selected"
        "slot": {
            "start": "2026-04-17T09:00:00Z",
            "end": "2026-04-17T11:00:00Z",
            "participants": [
                { "sub": "acc_5ba21743f408617d1269ea1e" },
                { "sub": "acc_64b17d868090ea21640c914c" }
            ]
        }
    }
}
```

###### no_slots_found
Sent by the Element when the provided `availability_query` has returned no available slots.

```js
{
    "notification": {
        "type": "no_slots_found"
    }
}
```

##### `data_center` *(optional)*

Designates the Cronofy data center the Element will communicate with.

Default value is `us`.

##### `config` *(optional)*

Use this object to add further configuration to the Element:

##### `config.mode` *(optional)*

The Slot Picker Element has two "modes" it can operate in:

- `confirm` (default)

- `no_confirm`

When in `confirm` mode, clicking a slot displays a confirmation view that allows a user to confirm their selection or return to the list of slots. The callback function will be called with a `slot_selected` notification when a user confirms their selected slot.

When in `no_confirm` mode, the "confirmation" step is skipped. In this mode, the callback function will be passed a slot_selected notification when a user selects a slot, without any confirmation step.

##### `config.logs` *(optional)*

Set the level of logging you want to appear in the console:

- `info`: show verbose logging (recommended for development use only).

- `warn`: (default) only log errors and warnings.

- `error`: only log errors.

- `none`: suppress all console output from the Element.

##### `confirm` *(optional)*

Boolean that defines if an extra "confirmation" step is used after a user selects a slot from the list. Defaults to `true`.

##### `styles` *(optional)*

An object that controls the pre-packaged element styles.

##### `styles.prefix` *(optional)*

Customizable elements are given a prefixed class name using this value. For
example, if the `prefix` was set as "Foo", the class name on a slot element
would be `Foo__slot`.

Defaults to `SlotPicker`.

##### `styles.padding` *(optional)*

The size of the padding around the edge of the element. Defaults to `1em`.

##### `demo` *(optional)*

Boolean to activate demo-mode. Defaults to `false`. If `demo` is set to `true`
the Element will return mock data (and not make any API calls).

##### `locale` *(optional)*

The Slot Picker supports localization (e.g. `locale: &quot;fr&quot;` to load in French). Defaults to browser language setting.

Supported locales (languages) for the UI Elements are:

- `ar` Arabic

- `cs` Czech

- `cy` Welsh

- `de` German

- `en` US English (default)

- `es` Spanish

- `fr` French

- `fr-CA` Canadian French

- `he` Hebrew

- `it` Italian

- `ja` Japanese

- `nl` Dutch

- `pl` Polish

- `pt-BR` Brazilian Portuguese

- `ru` Russian

- `sv` Swedish

- `tr` Turkish

- `zh-CN` Simplified Chinese

##### `translations` *(optional)*

To override either a locale or a particular string, pass in a translations object here. The Slot Picker uses the `slot_picker` translation "context".

[Read more about customizing translations](/developers/ui-elements/customization/index.md)

##### `tzid` *(optional)*

The time zone that the Slot Picker will be rendered in. Must be a known time zone
identifier from the [IANA Time Zone Database](https://www.iana.org/time-zones). If an invalid `tzid` is provided, then the Element will use the system time zone from the user's browser and trigger a [`warn` notification](/developers/ui-elements/index.md).

Be aware, using the `tzid` option will cause the Slot Picker to render in a timezone that may not match the timezone of the user's computer. Be sure to highlight this to the user.

### Element classes
`PREFIX` default is `SlotPicker`

Available classes:

- `{PREFIX}__slots-header`

- `{PREFIX}__slots-heading`

- `{PREFIX}__slot--empty`

- `{PREFIX}__slots-list`

- `{PREFIX}__slots-list--days`

- `{PREFIX}__slots-list--times`

- `{PREFIX}__slots-list--empty`

- `{PREFIX}__slot`

- `{PREFIX}__slot--unavailble`

- `{PREFIX}__slots-icon`

- `{PREFIX}__slots-icon--back`

- `{PREFIX}__slots-icon--tickmark`

- `{PREFIX}__slots-icon--remove`

- `{PREFIX}__confirmation-wrapper`

- `{PREFIX}__confirmation`

- `{PREFIX}__confirmation-summary`

- `{PREFIX}__confirmation-buttons`

- `{PREFIX}__confirmation-button`

### Element methods
##### `refresh()`

From time to time you may wish to reload the SlotPicker UI Element on the page. You can do this with the `SlotPicker.refresh()` method:

```js
// Load SlotPicker Element:
const SlotPicker = CronofyElements.SlotPicker(optionsObject);

// Refresh the SlotPicker Element:
SlotPicker.refresh();
```

> **WARNING:** Being able to refresh a UI Element is useful in cases where your availability may have changed behind the scenes. UI Elements gather their availability data when they are first loaded, so unless they are refreshed they will not be aware of any changes to availability.

##### `update()`

Should you need to update the `options` for any Element, you can reload them with the `.update()` method (this requires you to have saved your Element instance to a variable beforehand):

```js
// Load SlotPicker Element:
const SlotPicker = CronofyElements.SlotPicker(optionsObject);

// Update the SlotPicker Element with new options:
SlotPicker.update(newOptions);
```

When updating, you do not need to redeclare *all* the options; you just need to add the ones you want to update.

**Note:** the `SlotPicker.update()` method must be called with an options object, otherwise a [warning-level log notification](/developers/ui-elements/index.md) will be fired.



---
[Read in HTML](/developers/ui-elements/slot-picker/)