Widgets for Headless CMS
Widgets are interface elements in the Headless CMS that merchants can use to enhance store sections. These can include date pickers, dropdown menus, image uploaders, and more, helping editors create and edit content.
In this guide, you will find:

Widgets available

Below is a brief description of the widgets that can be implemented and used in the Headless CMS interface in the VTEX Admin. For detailed information about each widget, click the respective widget name.
Widget nameDescription
checkboxesDisplays checkboxes for selecting options in forms.
image-uploaderUploads images from your local machine.
date-timeProvides a calendar popup for selecting a date and time.
draftjs-rich-textRich text editor for formatting and styling store text.
media-galleryUploads or selects existing images or videos from the Media.

checkboxes

Displays a checkbox commonly used in forms to select an option. The following image shows how the checkboxes are displayed within the headless CMS interface:
An error occurred while loading the image https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-three___77a45e8e239de651e1169b6b15ebe222.gif

image-uploader

Displays a card to upload an image from your local machine. The following image shows how the image-uploader is displayed within the headless CMS interface:
An error occurred while loading the image https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-four___58dba186180d5e731436a06c41a8c454.png
The image-uploader is one of the available widgets. Still, we recommend using the media gallery widget, which allows you to select and upload not only images but also videos from the Media module.

date-time

Provides a calendar popup for selecting a date and time. It is ideal for displaying deadlines, event times, or any scenario where you need to specify a specific date and time within your headless CMS content. For example, you can showcase a product's expiration date or display a time-limited coupon badge. The following image shows how the date-time is displayed within the headless CMS interface:
An error occurred while loading the image https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-five___ddd15e6fbc00b8687276bd6bf6d72e78.gif

draftjs-rich-text

Displays an editor that allows formatting and styling the store text. The following image shows how the draftjs-rich-text is displayed within the headless CMS interface:
An error occurred while loading the image https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-six___b1c1f6a8a646661428c75d7e68dcdbd2.png
Displays a card to upload or select an existing image from the Media module. The following image shows how the media-gallery is displayed within the headless CMS interface:
The difference between the image-uploader and the media-gallery is that when you click the media-gallery property, you can select or upload an image or a video from the Media module. The image-uploader on the other hand, only allows you to upload images from your machine.
An error occurred while loading the image https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-seven___ab9decd87c30ee0c44428ff83dcae592.png

Adding a widget to a store section

Widgets are useful when you've created a new store section and want to add a new property to it. To illustrate how a widget can be used in a store section, here's an example using the media-gallery widget in the new Custom Newsletter section, based on the Newsletter native section.
To create a new section, such as the Custom Newsletter, follow the instructions in the guide Creating a new store section.
  1. Open your store project code in a code editor and navigate to the cms/faststore folder.
  2. Open the sections.json file.
  3. In the sections.json file, find the section where you want to add the widget. In the following sections.json file example, the new section, Custom Newsletter, receives the media-gallery widget.
  1. Open the terminal and run yarn cms-sync to sync the new section with the Headless CMS. Once the changes are synced, you will see the following message: info: CMS synced successfully....
  2. Go to the VTEX Admin and access Storefront > Headless CMS.
  3. Open the page where you want to add the new section. In this example, we will add the Custom Newsletter to Home.
  4. Add the section to the page, and you will notice the widget you added, the media-gallery.
    An error occurred while loading the image https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-one___6c8c5e28b43487efc6f6048afd8d8d15.gif
  5. Click Preview to view the new component with the new image.
    An error occurred while loading the image https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-two___9c76a69ce03639b33faa85eb2a7cb367.png
checkboxes
"activate": {
"title": "Activate Cupom",
"type": "boolean",
"default": true,
"widget": {
"ui:widget": "checkboxes"
}
},
Contributors
2
Photo of the contributor
Photo of the contributor
Was this helpful?
Yes
No
Suggest Edits (GitHub)