# Image

Source: https://decapcms.org/docs/widgets/image/ (updated 2026-10-26)


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_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`)
- `public_folder` *(defaults to the value of `media_folder`)*: specifies the folder path where the files uploaded by the media library will be accessed, relative to the base of the built site. The value of the field is generated by prepending this path to the filename of the selected file.
- `media_processing`: image transformation settings to apply to uploads from this field. Field-level settings override the top-level `media_processing` configuration. See [Media Processing](https://decapcms.org/docs/configuration-options/#media-processing) for available options.
- `choose_url`: *(default: `true`)* when set to `false`, the "Insert from URL" button will be hidden
- `media_library`: settings to apply when a media library is opened by the current widget. It accepts these options:
  - `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`, `public_folder`, `media_processing` and `choose_url` are options of the field itself. Don't put them under `media_library`.

**Example**

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

### Image Size Limit

You can set a limit on the maximum file size that users can upload directly into an image field.

**Example**

```yaml
  media_library:
    config:
      max_file_size: 512000 # in bytes, only for default media library
```

**Result**

![toggle switch](https://decapcms.org/img/widget-image.png)