# UI Elements ## Getting started? - [Online Booking TutorialThis tutorial will guide you through the process of integrating Cronofy into your own application. You'll see for yourself just how easy it is to check availability and schedule an event.](/developers/getting-started/online-booking-tutorial/index.md) UI Elements are JavaScript components that provide user interface overlays to various Cronofy API endpoints. > **INFO:** Latest release: v1.67.6 . See the [changelog](/developers/ui-elements/changelog/index.md) for details about recent releases. ## Installation All the UI Elements accept some global options, and each have additional Element-specific options. For all Elements, load them into your app by including the source `.js` file into your page. ``` https://elements.cronofy.com/js/CronofyElements.v1.67.6.js``` ### Using npm If you prefer, you can install the UI Elements with [npm](https://www.npmjs.com/package/cronofy-elements). ``` npm install --save cronofy-elements``` After installing, you will need to import the Elements into your JavaScript: ```js import * as CronofyElements from "cronofy-elements";``` ## Using UI Elements With the exception of the Calendar Sync element which is used to enroll users, each UI Element uses an authentication token called an Element Token. Element tokens are short-lived tokens with specific scopes, which are used to avoid exposing the much more powerful API access tokens in public. Once you have connected a user, you can [create an Element token](/developers/ui-elements/authentication/index.md) for them and pass it to your front-end code to initialize a UI Element. > **INFO:** Note that the [calendar sync](/developers/ui-elements/calendar-sync/index.md) component is special in that the Element Token is optional so that it can be used to on-board new users. Provided with an Element Token, it can also be used to help existing users manage their accounts. ## Initialize the Element Once you have included the UI Element in your project (either by importing from npm or including the source file), you can initialize the desired Element using the corresponding method and passing in options as an object. For example, to load the "Agenda" Element, your script would look like this: ```js CronofyElements.Agenda({ token: "YOUR_TOKEN", target: "cronofy-agenda" }); ``` ## Updating options 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 Element: const YourElement = CronofyElements.AvailabilityViewer(optionsObject); // Update the Element with new options: YourElement.update(newOptions); ``` When updating, you do not need to redeclare *all* the options; you just need to add the ones you want to update. For instance, the [AvailabilityViewer](/developers/ui-elements/availability-viewer/index.md) Element accepts several options, but when you're updating the options, you only need to include the options that are changing. ## Refreshing a UI Element From time to time you may wish to reload the UI Element on the page. You can do this with the `.refresh()` method: ```js // Load Element: const YourElement = CronofyElements.AvailabilityViewer(optionsObject); // Refresh the Element: YourElement.refresh(); ``` > **INFO:** 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. ## Context The context is an object representing useful context about the users browser. Currently the only key available is the `tzid`, the timezone ID being used by the element. If no `tzid` is set within the options object for a UI Element, this will return the browser's timezone. ```js // Load Element: const YourElement = CronofyElements.AvailabilityViewer(optionsObject); // Grab the tzid: const tzid = YourElement.context.tzid; ``` > **INFO:** This feature is only available from v1.28.0. ## Browser support UI Elements are officially supported on the last two versions of Chrome, Firefox, Safari, and Edge. ## Translations and localization Each of the elements support localization (e.g. `locale: "fr"` to load in French) via the `locale` initialization parameter. ### Supported locales - `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 Locales can be customized or added to by following the [instructions for customizing translation strings](/developers/ui-elements/customization/index.md). ### Locale modifiers Some locales have multiple valid options for localization. Locale modifiers allow you to opt into using these variations rather than the defaults. The modifiers block can be passed to all instances of an element, and will be applied when a user in the root locale views the element. For example, to have Japanese (`ja`) users see dates in the 'western' format: ```js locale_modifiers: { "ja": { "dates": "western" } } ``` #### Current values are:
Locale Modifier Value Effect
ja dates western Changes the date format to the westernised format: 
2021年 8月 23日 (月)
> **INFO:** This feature is only available from **v1.35.0**. ## Universal options These options can be applied to any of the UI Elements. See the individual element pages for element-specific options. ##### `data_center` *(optional)* Designates the Cronofy [data center](/developers/data-centers/index.md) the Element will communicate with. Default value is `us`. ##### `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. ##### `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). ##### `element_token` *(required)* The [Element Token](/developers/ui-elements/authentication/index.md) used by the element to communicate with Cronofy. ##### `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 the name of the element (e.g. `"AvailabilityViewer"`). ##### `target_id` *(required)* The ID of the DOM node the Element will be loaded in to. ##### `locale_modifiers` *(optional)* The mapping of locale to locale_modifier values to be used; see the description of [locale_modifiers](#locale-modifiers) for details on what can be set here. ##### `translations` *(optional)* To override either a locale or a particular string, pass in a translations object here. See the individual element pages for the element-specific `context`, and you can find [instructions for customizing translation strings](/developers/ui-elements/customization/index.md) on the UI Element Customizations page. ##### `callback` *(optional)* A function to be called when an action has occurred within a UI Element. Receives an object in the format: ```json { "notification": { "type": "notification_type" } } ``` ###### Log notifications All log events (`info`, `warn`, and `error`) fire a corresponding notification. The `notification.type` will match the log-level. Each of these notifications will include `element`, `message`, and `url` values. `notification.element` will be the name of the UI Element that fired the notification. `notification.message` will match the message passed to the logging function. `notification.url` will be a link to a relevant section of the UI Elements' documentation. For example, when running the Slot Picker with the `demo` option set to `true`, the following notification will be fired: ```json { "notification": { "type": "error", "element": "Slot Picker", "message": "You are running in demo mode. No API requests will be made", "url": "https://docs.cronofy.com/developers/ui-elements/", "errors": {} } } ``` The `error` notification type contains an `errors` property. If the error has a response body (for example, in the case of [`422` errors from the API](/developers/api/error-codes/index.md) then that object will be included here. If there is no body to show, this field will be an empty object. For example, here is the notification showing the API error when we have made an Availability Query which includes a `sub` we don't have access to: ```json { "notification": { "type": "error", "element": "Availability Viewer", "message": "There was a problem with your availability query.", "url": "https://docs.cronofy.com/developers/ui-elements/availability-viewer/#availability_query", "errors": { "participant[sub=acc_600eb48068ed0f33f6d4abad]": [ { "key": "errors.not_recognized", "description": "not recognized" } ] } } } ``` --- [Read in HTML](/developers/ui-elements/) ## In this section - [Authentication](/developers/ui-elements/authentication/index.md) — Authentication is by way of a specialized, short-lived token locked to a specific operation and origin. - [Agenda View](/developers/ui-elements/agenda-viewer/index.md) — Provides a navigable calendar view for the authenticated user. - [Date Time Picker](/developers/ui-elements/date-time-picker/index.md) — A date and time picker to allow a user to choose a date and a time based on rules defined in an availability query. - [Slot Picker](/developers/ui-elements/slot-picker/index.md) — A pared down slot picker to allow a user to choose a time based on rules defined in an availability query. - [Availability Rules](/developers/ui-elements/availability-rules/index.md) — A rich element for viewing and setting your weekly work hours. - [Availability Viewer](/developers/ui-elements/availability-viewer/index.md) — A rich element for navigating the results of an availability query and choosing slots. - [Calendar Sync](/developers/ui-elements/calendar-sync/index.md) — A rich element for managing profile synchronization. - [Debugging](/developers/ui-elements/debugging/index.md) — UI Elements have logging options to help you diagnose issues. - [Customizing the UI Elements](/developers/ui-elements/customization/index.md) — Theming and styling the UI Elements - [Using UI Elements within a React application](/developers/ui-elements/react/index.md) — How to use UI Elements inside a React application