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: An overview of each widget and its function.
Instructions on how to add a widget to a section: A guide with instructions on incorporating a widget into a new store section.

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 name	Description
`checkboxes`	Displays checkboxes for selecting options in forms.
`image-uploader`	Uploads images from your local machine.
`date-time`	Provides a calendar popup for selecting a date and time.
`draftjs-rich-text`	Rich text editor for formatting and styling store text.
`media-gallery`	Uploads 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:

${"base64":" ","img":{"width":543,"height":107,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":46888,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-three___77a45e8e239de651e1169b6b15ebe222.gif"}}$

checkboxes


_10"activate": {
_10    "title": "Activate Cupom",
_10     "type": "boolean",
_10     "default": true,
_10     "widget": {
_10         "ui:widget": "checkboxes"
_10     }
_10},

`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:

${"base64":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAABCAIAAAB2XpiaAAAACXBIWXMAABYlAAAWJQFJUiTwAAAAFUlEQVR4nGNIz8g0M7cwM7eYMHEiABkzBDVqZuuBAAAAAElFTkSuQmCC","img":{"src":"https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-four___58dba186180d5e731436a06c41a8c454.png","width":750,"height":238,"type":"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.

checkboxes

image-uploader


_10"imageSrc": {
_10   "type": "string",
_10    "title": "Image",
_10    "widget": {
_10        "ui:widget": "image-uploader"
_10     }
_10 }

`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:

${"base64":" ","img":{"width":621,"height":420,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":123732,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-five___ddd15e6fbc00b8687276bd6bf6d72e78.gif"}}$

checkboxes

image-uploader

date-time


_10"dateAndTime": {
_10    "title": "Calendar",
_10    "type": "string",
_10    "widget": {
_10       "ui:widget": "date-time"
_10     }
_10 },

`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:

${"base64":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAACCAIAAADwyuo0AAAACXBIWXMAABYlAAAWJQFJUiTwAAAAIElEQVR4nGOYP3/+PTCYP38+Q2Njo6en5/z58/ft2wcA03kPZLKAjLAAAAAASUVORK5CYII=","img":{"src":"https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-six___b1c1f6a8a646661428c75d7e68dcdbd2.png","width":574,"height":223,"type":"png"}}$

checkboxes

image-uploader

date-time

draftjs-rich-text


_10"richText": {
_10    "title": "Text editor",
_10    "type": "string",
_10    "widget": {
_10       "ui:widget": "draftjs-rich-text"
_10     }
_10 },

`media-gallery`

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.

${"base64":" ","img":{"width":577,"height":254,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":9464,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-seven___ab9decd87c30ee0c44428ff83dcae592.png"}}$

checkboxes

image-uploader

date-time

draftjs-rich-text

media-gallery


_10"mediaGallery": {
_10    "title": "Media Gallery",
_10    "type": "string",
_10    "widget": {
_10       "ui:widget": "media-gallery"
_10     }
_10 },

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.

Open your store project code in a code editor and navigate to the cms/faststore folder.
Open the sections.json file.
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.

checkboxes

image-uploader

date-time

draftjs-rich-text

media-gallery

sections.json


_144    …
_144    {
_144      "name": "CustomNewsletter",
_144      "requiredScopes": [],
_144      "schema": {
_144        "title": "Custom Newsletter",
_144        "description": "Short description for the section's purpose",
_144        "type": "object",
_144        "required": ["title"],
_144        "properties": {
_144          "icon": {
_144            "title": "Icon",
_144            "type": "object",
_144            "properties": {
_144              "icon": {
_144                "title": "Icon",
_144                "type": "string",
_144                "enumNames": ["Envelope"],
_144                "enum": ["Envelope"],
_144                "default": "Envelope"
_144              },
_144              "alt": {
_144                "type": "string",
_144                "title": "Alternative Label",
_144                "default": "Envelope"
_144              }
_144            }
_144          },
_144          "title": {
_144            "title": "Title",
_144            "type": "string",
_144            "default": "Get News and Special Offers!"
_144          },
_144          "mediaGallery": {
_144            "title": "Media Gallery",
_144            "type": "string",
_144            "widget": {
_144              "ui:widget": "media-gallery"
_144            }
_144          },
_144          "description": {
_144            "title": "Description",
_144            "type": "string",
_144            "default": "Receive our news and promotions in advance"
_144          },
_144          "privacyPolicy": {
_144            "title": "Privacy Policy Disclaimer",
_144            "type": "string",
_144            "widget": {
_144              "ui:widget": "draftjs-rich-text"
_144            }
_144          },
_144          "emailInputLabel": {
_144            "title": "Email input label",
_144            "type": "string",
_144            "default": "Your Email"
_144          },
_144          "displayNameInput": {
_144            "title": "Request name?",
_144            "type": "boolean",
_144            "default": true
_144          },
_144          "nameInputLabel": {
_144            "title": "Name input label",
_144            "type": "string",
_144            "default": "Your Name"
_144          },
_144          "subscribeButtonLabel": {
_144            "title": "Subscribe button label",
_144            "type": "string",
_144            "default": "Subscribe"
_144          },
_144          "subscribeButtonLoadingLabel": {
_144            "title": "Subscribe button loading label",
_144            "type": "string",
_144            "default": "Loading..."
_144          },
_144          "card": {
_144            "title": "Newsletter should be in card format?",
_144            "type": "boolean",
_144            "default": false
_144          },
_144          "colorVariant": {
_144            "title": "Color variant",
_144            "type": "string",
_144            "enumNames": ["Main", "Light", "Accent"],
_144            "enum": ["main", "light", "accent"],
_144            "default": "main"
_144          },
_144          "toastSubscribe": {
_144            "title": "Toast Subscribe",
_144            "type": "object",
_144            "properties": {
_144              "title": {
_144                "title": "Title",
_144                "description": "Message Title",
_144                "type": "string",
_144                "default": "Hooray!"
_144              },
_144              "message": {
_144                "title": "Message",
_144                "description": "Message",
_144                "type": "string",
_144                "default": "Thank you for your subscription."
_144              },
_144              "icon": {
_144                "title": "Icon",
_144                "type": "string",
_144                "enumNames": ["CircleWavyCheck"],
_144                "enum": ["CircleWavyCheck"],
_144                "default": "CircleWavyCheck"
_144              }
_144            }
_144          },
_144          "toastSubscribeError": {
_144            "title": "Toast Subscribe Error",
_144            "type": "object",
_144            "properties": {
_144              "title": {
_144                "title": "Title",
_144                "description": "Message Title",
_144                "type": "string",
_144                "default": "Oops."
_144              },
_144              "message": {
_144                "title": "Message",
_144                "description": "Message",
_144                "type": "string",
_144                "default": "Something went wrong. Please try again."
_144              },
_144              "icon": {
_144                "title": "Icon",
_144                "type": "string",
_144                "enumNames": ["CircleWavyWarning"],
_144                "enum": ["CircleWavyWarning"],
_144                "default": "CircleWavyWarning"
_144              }
_144            }
_144          }
_144        }
_144      }
_144    },
_144
_144  …

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....
Go to the VTEX Admin and access Storefront > Headless CMS.
Open the page where you want to add the new section. In this example, we will add the Custom Newsletter to Home.
Add the section to the page, and you will notice the widget you added, the media-gallery.

${"base64":" ","img":{"width":1368,"height":854,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":1741010,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-one___6c8c5e28b43487efc6f6048afd8d8d15.gif"}}$
Click Preview to view the new component with the new image.

${"base64":" ","img":{"width":1142,"height":558,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":108362,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-two___9c76a69ce03639b33faa85eb2a7cb367.png"}}$

`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:

`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:

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`

`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:

`media-gallery`

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.

To create a new section, such as the Custom Newsletter, follow the instructions in the guide Creating a new store section.

Open your store project code in a code editor and navigate to the cms/faststore folder.
Open the sections.json file.
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.

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....
Go to the VTEX Admin and access Storefront > Headless CMS.
Open the page where you want to add the new section. In this example, we will add the Custom Newsletter to Home.
Add the section to the page, and you will notice the widget you added, the media-gallery.

${"base64":" ","img":{"width":1368,"height":854,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":1741010,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-one___6c8c5e28b43487efc6f6048afd8d8d15.gif"}}$
Click Preview to view the new component with the new image.

${"base64":" ","img":{"width":1142,"height":558,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":108362,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/scoped-widgets-two___9c76a69ce03639b33faa85eb2a7cb367.png"}}$

checkboxes


_10"activate": {
_10    "title": "Activate Cupom",
_10     "type": "boolean",
_10     "default": true,
_10     "widget": {
_10         "ui:widget": "checkboxes"
_10     }
_10},

Widgets available

`checkboxes`

`image-uploader`

`date-time`

`draftjs-rich-text`

`media-gallery`

Adding a widget to a store section

`checkboxes`

`image-uploader`

`date-time`

`draftjs-rich-text`

`media-gallery`

Adding a widget to a store section