---
url: /en/docs/fields/image.md
description: >-
  Upload, manage, and reference images in Sveltia CMS with flexible storage
  options.
---

# Image Field

The Image field type allows users to upload and manage images within the CMS. It’s basically an alias of the [File](/en/docs/fields/file) field type but limited to image files.

The `widget` property for this field type is `image`.

See the [File field documentation](/en/docs/fields/file) for details on the UI, data type, and available options. Note that the `select_folder` option is not available for the Image field type.

## Examples

### Standard Image Field

This example shows a basic Image field.

::: code-group

```yaml [YAML]
- name: image
  label: Image
  widget: image
```

```toml [TOML]
[[fields]]
name = "image"
label = "Image"
widget = "image"
```

```json [JSON]
{
  "name": "image",
  "label": "Image",
  "widget": "image"
}
```

```js [JavaScript]
{
  name: 'image',
  label: 'Image',
  widget: 'image',
}
```

:::

Output example:

::: code-group

```yaml [YAML]
image: /uploads/photo.jpg
```

```toml [TOML]
image = "/uploads/photo.jpg"
```

```json [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](/en/docs/fields/object) to group the image source and alt text together.

::: code-group

```yaml [YAML]
- name: image
  widget: object
  fields:
    - { name: src, widget: image }
    - { name: alt, widget: string }
```

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

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

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

:::

Output example:

::: code-group

```yaml [YAML]
image:
  src: /uploads/photo.jpg
  alt: A beautiful sunset
```

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

```json [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.

::: code-group

```yaml [YAML]
- name: gallery
  label: Gallery
  widget: image
  multiple: true
  min: 2
  max: 5
  accept: image/webp
```

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

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

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

:::

Output example:

::: code-group

```yaml [YAML]
gallery:
  - /uploads/photo1.webp
  - /uploads/photo2.webp
  - /uploads/photo3.webp
```

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

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

:::