Image Field

The Image field type allows users to upload and manage images within the CMS. It’s basically an alias of the File field type but limited to image files.

The widget property for this field type is image.

See the File field documentation for details on the UI, data type, and available options.

Examples

Standard Image Field

This example shows a basic Image field.

YAML

- name: image
  label: Image
  widget: image

TOML

[[fields]]
name = "image"
label = "Image"
widget = "image"

JSON

{
  "name": "image",
  "label": "Image",
  "widget": "image"
}

JavaScript

{
  name: 'image',
  label: 'Image',
  widget: 'image',
}

Output example:

YAML

image: /uploads/photo.jpg

TOML

image = "/uploads/photo.jpg"

JSON

{
  "image": "/uploads/photo.jpg"
}

Image Field with Alt Text

To include additional metadata such as alt text for accessibility, you can use an object field to group the image source and alt text together.

YAML

- name: image
  widget: object
  fields:
    - { name: src, widget: image }
    - { name: alt, widget: string }

TOML

[[fields]]
name = "image"
widget = "object"
[[fields.fields]]
name = "src"
widget = "image"
[[fields.fields]]
name = "alt"
widget = "string"

JSON

{
  "name": "image",
  "widget": "object",
  "fields": [
    { "name": "src", "widget": "image" },
    { "name": "alt", "widget": "string" }
  ]
}

JavaScript

{
  name: 'image',
  widget: 'object',
  fields: [
    { name: 'src', widget: 'image' },
    { name: 'alt', widget: 'string' },
  ],
}

Output example:

YAML

image:
  src: /uploads/photo.jpg
  alt: A beautiful sunset

TOML

[image]
src = "/uploads/photo.jpg"
alt = "A beautiful sunset"

JSON

{
  "image": {
    "src": "/uploads/photo.jpg",
    "alt": "A beautiful sunset"
  }
}

In the future, we may add built-in support for alt text and other metadata directly within the Image field type.

Multiple Image Uploads with Restrictions

This example shows how to allow multiple image uploads using the multiple option, along with minimum and maximum limits and file type restrictions.

YAML

- name: gallery
  label: Gallery
  widget: image
  multiple: true
  min: 2
  max: 5
  accept: image/webp

TOML

[[fields]]
name = "gallery"
label = "Gallery"
widget = "image"
multiple = true
min = 2
max = 5
accept = "image/webp"

JSON

{
  "name": "gallery",
  "label": "Gallery",
  "widget": "image",
  "multiple": true,
  "min": 2,
  "max": 5,
  "accept": "image/webp"
}

JavaScript

{
  name: 'gallery',
  label: 'Gallery',
  widget: 'image',
  multiple: true,
  min: 2,
  max: 5,
  accept: 'image/webp',
}

Output example:

YAML

gallery:
  - /uploads/photo1.webp
  - /uploads/photo2.webp
  - /uploads/photo3.webp

TOML

gallery = ["/uploads/photo1.webp", "/uploads/photo2.webp", "/uploads/photo3.webp"]

JSON

{
  "gallery": ["/uploads/photo1.webp", "/uploads/photo2.webp", "/uploads/photo3.webp"]
}