Tag: Widgets

The color widget translates a color picker to a color string.

• Name: color
• UI: color picker
• Data type: string
• Options:
  • default: accepts a string; defaults to an empty string. Sets the default value
  • allowInput: accepts a boolean, defaults to false. Allows manual editing of the color input value
  • enableAlpha: accepts a boolean, defaults to false. Enables Alpha editing
• Example:

  - { label: 'Color', name: 'color', widget: 'color' }

• Example:

  - { label: 'Color', name: 'color', widget: 'color', enableAlpha: tru

Deprecation notice: the date widget has been deprecated and will be removed in the next major release. Please use the datetime widget instead.

The date widget translates a date picker input to a date string. For saving date and time together, use the datetime widget.

• Name: date
• UI: date picker
• Data type: Moment.js-formatted date string
• Options:
  • default: accepts a date string, or an empty string to accept blank input; otherwise defaults to current date
  • format: optional; accepts Moment.js tokens; defaults to raw Date object (if supported by output format)
  • date_format: optional; boolean or Moment.js tokens. If true use default locale format.
  • time_format: optional; boolean or Moment.js tokens. If true use default locale format, false hides time-picker. Defaults to false.
• Example:

  - label: 'Birthdate'
    name: 'birthdate'
    widget: 'date'
    default: ''
    format: 'MMM Do YY'

The datetime widget translates a datetime picker to a datetime string.

• Name: datetime
• UI: datetime picker
• Data type: Moment.js-formatted datetime string
• Options:
  • default: accepts a datetime string, or an empty string to accept blank input; otherwise defaults to current datetime
  • format: sets storage format; accepts Moment.js tokens; defaults to raw Date object (if supported by output format)
  • date_format: sets date display format in UI; boolean or Moment.js tokens. If true use default locale format.
  • time_format: sets time display format in UI; boolean or Moment.js tokens. If true use default locale format, false hides time-picker.
  • picker_utc: (default: false) when set to true, the datetime picker will display times in UTC. When false, the datetime picker will display times in the user’s local timezone. When using date-only formats, it can be helpful to set this to true so users in all timezones will see the same date in the datetime picker.
• Example:

  - label: "Start time"
    name: "start"
    widget: "datetime"
    default: ""
    date_format: "DD.MM.YYYY" # e.g. 24.12.2021
    time_format: "HH:mm" # e.g. 21:07
    format: "LLL"
    picker_utc: false

The file widget allows editors to upload a file or select an existing one from the media library. The path to the file will be saved to the field as a string.

• Name: file
• UI: file picker button opens media gallery
• Data type: file path string
• Options:
  • default: accepts a file path string; defaults to null
  • media_library: media library settings to apply when a media library is opened by the current widget
    • allow_multiple: (default: true) when set to false, prevents multiple selection for any media library extension, but must be supported by the extension in use
    • config: a configuration object that will be passed directly to the media library being used – available options are determined by the library
    • media_folder (Beta): file path where uploaded files will be saved specific to this control. Paths can be relative to a collection folder (e.g. files will add the file to a sub-folder in the collection folder) or absolute with reference to the base of the repo which needs to begin with / (e.g /static/files will save uploaded files to the static folder in a sub folder named files)
    • choose_url: (default: true) when set to false, the “Insert from URL” button will be hidden
• Example:

  - label: "Manual PDF"
    name: "manual_pdf"
    widget: "file"
    default: "/uploads/general-manual.pdf"
    media_library:
      config:
        multiple: true

Hidden widgets do not display in the UI. In folder collections that allow users to create new items, you will often want to set a default for hidden fields, so they will be set without requiring an input.

• Name: hidden
• UI: none
• Data type: any valid data type
• Options:
  • default: accepts any valid data type; recommended for collections that allow adding new items
• Example:

  - {label: "Layout", name: "layout", widget: "hidden", default: "blog"

The image widget allows editors to upload an image or select an existing one from the media library. The path to the image file will be saved to the field as a string.

• Name: image
• UI: file picker button opens media gallery allowing image files (jpg, jpeg, webp, gif, png, bmp, tiff, svg) only; displays selected image thumbnail
• Data type: file path string
• Options:
  • default: accepts a file path string; defaults to null
  • media_library: settings to apply when a media library is opened by the current widget
  • allow_multiple: (default: true) when set to false, multiple selection will be disabled even if the media library extension supports it
  • config: a configuration object passed directly to the media library; check the documentation of your media library extension for available config options
  • media_folder (Beta): file path where uploaded images will be saved specific to this control. Paths can be relative to a collection folder (e.g. images will add the image to a sub-folder in the collection folder) or absolute with reference to the base of the repo which needs to begin with / (e.g /static/images will save uploaded images to the static folder in a sub folder named images)
  • choose_url: (default: true) when set to false, the “Insert from URL” button will be hidden
• Example:

  - label: "Featured Image"
    name: "thumbnail"
    widget: "image"
    choose_url: true
    default: "/uploads/chocolate-dogecoin.jpg"
    media_library:
      config:
        multiple: true

The list widget allows you to create a repeatable item in the UI which saves as a list of widget values. map a user-provided string with a comma delimiter into a list. You can choose any widget as a child of a list widget—even other lists.

• Name: list
• UI: without any fields specified, the list widget defaults to a text input for entering comma-separated values; with fields specified, the list widget contains a repeatable child widget, with controls for adding, deleting, and re-ordering the repeated widgets.
• Data type: list of widget values
• Options:
  • default: you may specify a list of strings to populate the basic text field, or an array of list items for lists using the fields option. If no default is declared when using field or fields, will default to a single list item using the defaults on the child widgets
  • allow_add: false hides the button to add additional items
  • collapsed: when true, the entries collapse by default
  • summary: specify the label displayed on collapsed entries
  • minimize_collapsed: when true, collapsing the list widget will hide all of it’s entries instead of showing summaries
  • label_singular: the text to show on the add button
  • field: a single widget field to be repeated
  • fields: a nested list of multiple widget fields to be included in each repeatable iteration
  • max: maximum number of items in the list
  • min: minimum number of items in the list
  • add_to_top: when true, new entries will be added to the top of the list
• Example (field/fields not specified):

- label: "Tags"
  name: "tags"
  widget: "list"
  default: ["news"]

• Example (allow_add marked false):

- label: "Tags"
  name: "tags"
  widget: "list"
  allow_add: false
  default: ["news"]

• Example (with field):

- label: "Gallery"
  name: "galleryImages"
  widget: "list"
  summary: '{{fields.image}}'
  field: {label: Image, name: image, widget: image}

• Example (with fields):

- label: "Testimonials"
  name: "testimonials"
  widget: "list"
  summary: '{{fields.quote}} - {{fields.author.name}}'
  fields:
    - {label: Quote, name: quote, widget: string, default: "Everything is awesome!"}
    - label: Author
      name: author
      widget: object
      fields:
        - {label: Name, name: name, widget: string, default: "Emmet"}
        - {label: Avatar, name: avatar, widget: image, default: "/img/emmet.jpg"}

• Example (with default):

- label: "Gallery"
  name: "galleryImages"
  widget: "list"
  fields:
    - { label: "Source", name: "src", widget: "string" }
    - { label: "Alt Text", name: "alt", widget: "string" }
  default:
    - { src: "/img/tennis.jpg", alt: "Tennis" }
    - { src: "/img/footbar.jpg", alt: "Football" }

• Example (collapsed marked false):

- label: "Testimonials"
  name: "testimonials"
  collapsed: false
  widget: "list"
  fields:
    - {label: Quote, name: quote, widget: string, default: "Everything is awesome!"}
    - {label: Author, name: author, widget: string }

• Example (minimize_collapsed marked true):

- label: "Testimonials"
  name: "testimonials"
  minimize_collapsed: true
  widget: "list"
  fields:
    - {label: Quote, name: quote, widget: string, default: "Everything is awesome!"}
    - {label: Author, name: author, widget: string }

• Example (with max & min):

- label: "Tags"
  name: "tags"
  widget: "list"
  max: 3
  min: 1
  default: ["news"]

• Example (add_to_top marked true):

- label: "Tags"
  name: "tags"
  widget: "list"
  add_to_top: true

The map widget allows you to edit spatial data using an interactive map. Spatial data for a single piece of geometry saves as a GeoJSON string in WGS84 projection.

• Name: map
• UI: interactive map
• Data type: GeoJSON string
• Options:
  • decimals: accepts a number to specify precision of saved coordinates; defaults to 7 decimals
  • default: accepts a GeoJSON string containing a single geometry; defaults to an empty string
  • type: accepts one string value of Point, LineString or Polygon; defaults to Point
• Example:

  - {label: "Location", name: "location", widget: "map" }

The markdown widget provides a full fledged text editor allowing users to format text with features such as headings and blockquotes. Users can change their editing view with a handy toggle button.

Please note: If you want to use your markdown editor to fill a markdown file contents after its frontmatter, you’ll have to name the field body so the CMS recognizes it and saves the file accordingly.

• Name: markdown
• UI: full text editor
• Data type: markdown
• Options:
  • default: accepts markdown content
  • minimal: accepts a boolean value, false by default. Sets the widget height to minimum possible.
  • buttons: an array of strings representing the formatting buttons to display (all shown by default). Buttons include: bold, italic, code, link, heading-one, heading-two, heading-three, heading-four, heading-five, heading-six, quote, bulleted-list, and numbered-list.
  • editor_components: an array of strings representing the names of editor components to display (all shown by default). Netlify CMS includes image and code-block editor components by default, and custom components may be created and registered.
  • modes: an array of strings representing the names of allowed editor modes. Possible modes are raw and rich_text. A toggle button appears in the toolbar when more than one mode is available.
  • sanitize_preview: accepts a boolean value, false by default. Sanitizes markdown preview to prevent XSS attacks – might alter the preview content.
• Example:

  - { label: 'Blog post content', name: 'body', widget: 'markdown' }

This would render as:

Please note: The markdown widget outputs a raw markdown string. Your static site generator may or may not render the markdown to HTML automatically. Consult with your static site generator’s documentation for more information about rendering

Number

markdown.

The object widget allows you to group multiple widgets together, nested under a single field. You can choose any widget as a child of an object widget—even other objects.

• Name: object
• UI: a field containing one or more child widgets
• Data type: list of child widget values
• Options:
  • default: you can set defaults within each sub-field’s configuration
  • collapsed: if added and labeled true, collapse the widget’s content by default
  • summary: specify the label displayed when the object is collapsed
  • fields: (required) a nested list of widget fields to include in your widget
• Example:

  - label: "Profile"
    name: "profile"
    widget: "object"
    summary: '{{fields.name}}: {{fields.birthdate}}'
    fields:
      - {label: "Public", name: "public", widget: "boolean", default: true}
      - {label: "Name", name: "name", widget: "string"}
      - label: "Birthdate"
        name: "birthdate"
        widget: "date"
        default: ""
        format: "MM/DD/YYYY"
      - label: "Address"
        name: "address"
        widget: "object"
        collapsed: true
        fields: 
          - {label: "Street Address", name: "street", widget: "string"}
          - {label: "City", name: "city", widget: "string"}
          - {label: "Postal Code", name: "post-code", widget: "string"

The relation widget allows you to reference items from another collection. It provides a search input with a list of entries from the collection you’re referencing, and the list automatically updates with matched entries based on what you’ve typed.

• Name: relation
• UI: text input with search result dropdown
• Data type: data type of the value pulled from the related collection item
• Options:
  • collection: (required) name of the referenced collection (string)
  • value_field: (required) name of the field from the referenced collection whose value will be stored for the relation. For nested fields, separate each subfield with a . (e.g. name.first). For list fields use a wildcard * to target all list items (e.g. categories.*).
  • search_fields: (required) list of one or more names of fields in the referenced collection to search for the typed value. Syntax to reference nested fields is similar to that of value_field.
  • file: allows referencing a specific file when the referenced collection is a files collection (string)
  • display_fields: list of one or more names of fields in the referenced collection that will render in the autocomplete menu of the control. Defaults to value_field. Syntax to reference nested fields is similar to that of value_field.
  • default: accepts any widget data type; defaults to an empty string
  • multiple : accepts a boolean, defaults to false
  • min: minimum number of items; ignored if multiple is false
  • max: maximum number of items; ignored if multiple is false
  • options_length: accepts integer to override number of options presented to user. Defaults to 20.
• Referencing a folder collection example (assuming a separate “authors” collection with “name” and “twitterHandle” fields with subfields “first” and “last” for the “name” field):

- label: "Post Author"
  name: "author"
  widget: "relation"
  collection: "authors"
  search_fields: ["name.first", "twitterHandle"]
  value_field: "name.first"
  display_fields: ["twitterHandle", "followerCount"]

The generated UI input will search the authors collection by name and twitterHandle, and display each author’s handle and follower count. On selection, the author’s name is saved for the field.

• String templates example (assuming a separate “authors” collection with “name” and “twitterHandle” fields with subfields “first” and “last” for the “name” field):

- label: "Post Author"
  name: "author"
  widget: "relation"
  collection: "authors"
  search_fields: ['name.first']
  value_field: "{{slug}}"
  display_fields: ["{{twitterHandle}} - {{followerCount}}"]

The generated UI input will search the authors collection by name, and display each author’s handle and follower count. On selection, the author entry slug is saved for the field.

• Referencing a file collection list field example (assuming a separate “relation_files” collection with a file named “cities” with a list field “cities” with subfields “name” and “id”):

- label: "City"
  name: "city"
  widget: "relation"
  collection: "relation_files"
  file: "cities"
  search_fields: ["cities.*.name"]
  display_fields: ["cities.*.name"]
  value_field: "cities.*.id"

The generated UI input will search the cities file by city name, and display each city’s name. On selection, the city id is saved for the field.

The select widget allows you to pick a string value from a dropdown menu.

• Name: select
• UI: select input
• Data type: string or array
• Options:
  • default: options must contain any default values
    • string values: accepts a string; defaults to an empty string. Accepts an array of strings and defaults to an empty array with multiple: true enabled.
    • object with label and value fields: accepts an object with label and value field or an array of such objects when multiple: true is enable. Defaults to no value
  • options: (required) there are two ways to list of options for the dropdown menu:
    • string values: the dropdown displays the value directly
    • object with label and value fields: the label displays in the dropdown; the value saves in the file
  • multiple: accepts a boolean; defaults to false
  • min: minimum number of items; ignored if multiple is false
  • max: maximum number of items; ignored if multiple is false
• Example (options as strings):

- label: "Align Content"
  name: "align"
  widget: "select"
  options: ["left", "center", "right"]

Selecting the center option, will save the value as:

align: "center"

• Example (options as objects):

- label: "City"
  name: "airport-code"
  widget: "select"
  options:
    - { label: "Chicago", value: "ORD" }
    - { label: "Paris", value: "CDG" }
    - { label: "Tokyo", value: "HND" }

Selecting the Chicago option, will save the value as:

airport-code: "ORD"

• Example (multiple):

- label: "Tags"
  name: "tags"
  widget: "select"
  multiple: true
  options: ["Design", "UX", "Dev"]
  default: ["Design"]

• Example (min/max):

- label: "Tags"
  name: "tags"
  widget: "select"
  multiple: true
  min: 1
  max: 3
  options: ["Design", "UX", "Dev"]
  default: ["Design"]

The string widget translates a basic text input to a string value. For larger textarea inputs, use the text widget.

• Name: string
• UI: text input
• Data type: string
• Options:
  • default: accepts a string; defaults to an empty string
• Example:

  - {label: "Title", name: "title", widget: "string"}

The text widget takes a multiline text field and saves it as a string. For shorter text inputs, use the string widget.

• Name: text
• UI: HTML textarea
• Data type: string
• Options:
  • default: accepts a string; defaults to an empty string
• Example:

  - {label: "Description", name: "description", widget: "text"}