☁️ Loving our new documentation website? Provide feedback in the CloudCannon Community! ✨

Developer ReferenceConfiguration File

image

Table of contents

Description:

This key defines input options for image Editable Regions.

Appears in:
└── _editables
    └── image
Type:
Object
Properties:
allowed_sourcesArray<allowed_sources[*]>#

This key defines which sources and DAMs you are allowed to upload to and browse.

The value can be an array of strings. Valid values include site-files and the reference key for any DAM connected to your site.

If site-files is omitted from the array, site files will not be available as an asset source for this input.

Show examplesHide examples

In this example, we have configured allowed sources for an Image Input.

Copied to clipboard
_inputs:
  image:
    type: image
    options:
      allowed_sources:
        - site-files
        - my-cloudinary-dam
{
  "_inputs": {
    "image": {
      "type": "image",
      "options": {
        "allowed_sources": [
          "site-files",
          "my-cloudinary-dam"
        ]
      }
    }
  }
}
expandableboolean#

This key defines whether you can upscale an image to fit the bounding box while resizing an image prior to upload.

Has no effect if files are not resized.

Defaults to: false

Show examplesHide examples

In this example, we have configured an Image Input to allow upscaling images to fit the bounding box while resizing.

Copied to clipboard
_inputs:
  hero_image:
    type: image
    options:
      width: 1200
      height: 600
      resize_style: cover
      expandable: true
{
  "_inputs": {
    "hero_image": {
      "type": "image",
      "options": {
        "width": 1200,
        "height": 600,
        "resize_style": "cover",
        "expandable": true
      }
    }
  }
}
heightnumber#

This key defines the height of the bounding box used in the resizing method defined by resize_style.

Show examplesHide examples

In this example, we have configured the height of the bounding box for an Image Input.

Copied to clipboard
_inputs:
  hero_image:
    type: image
    options:
      width: 1200
      height: 600
      resize_style: cover
{
  "_inputs": {
    "hero_image": {
      "type": "image",
      "options": {
        "width": 1200,
        "height": 600,
        "resize_style": "cover"
      }
    }
  }
}
image_size_attributesboolean#

This key toggles whether CloudCannon will instruct a rich text editor to save width and height attributes on image elements.

Setting this key to true will instruct the rich text editor to save width and height attributes on image elements. This can prevent pop-in as a page loads.

By default, this key is false (i.e., width and height attributes are not saved on image elements). This defaults to true if the Image Size Attributes site flag is enabled (this is enabled for sites created before June 23 2023, in order to keep those sites working).

Defaults to: true

Show examplesHide examples

In this example, CloudCannon will save width and height attributes on image elements in a Rich Text Input.

Copied to clipboard
_inputs:
  content:
    type: markdown
    options:
      image_size_attributes: true
{
  "_inputs": {
    "content": {
      "type": "markdown",
      "options": {
        "image_size_attributes": true
      }
    }
  }
}
mime_typestring#

This key defines what format an image is converted to prior to upload.

Allowed values: image/jpeg image/png image/webp

Show examplesHide examples

In this example, we have configured an Image Input to convert images to WebP format prior to upload.

Copied to clipboard
_inputs:
  hero_image:
    type: image
    options:
      mime_type: image/webp
{
  "_inputs": {
    "hero_image": {
      "type": "image",
      "options": {
        "mime_type": "image/webp"
      }
    }
  }
}
pathsObject#

This key defines paths for your Rich Text editors or File inputs.

If undefined at higher levels of the configuration cascade, paths will default to any values configured in the CloudCannon configuration file.

Show examplesHide examples

In this example, we have configured paths for the blog Collection to set custom upload and static paths.

Copied to clipboard
collections_config:
  blog:
    paths:
      uploads: /uploads/blog/
      static: /assets/
{
  "collections_config": {
    "blog": {
      "paths": {
        "uploads": "/uploads/blog/",
        "static": "/assets/"
      }
    }
  }
}
prevent_resize_existing_filesboolean#

This key toggles whether CloudCannon will skip the image resizing process configured for this input when selecting existing images.

Setting this key to true will skip the image resizing process when selecting existing images.

Defaults to: false

Show examplesHide examples

In this example, CloudCannon will skip the image resizing process when selecting existing images for an Image Input.

Copied to clipboard
_inputs:
  hero_image:
    type: image
    options:
      width: 1200
      height: 600
      resize_style: cover
      prevent_resize_existing_files: true
{
  "_inputs": {
    "hero_image": {
      "type": "image",
      "options": {
        "width": 1200,
        "height": 600,
        "resize_style": "cover",
        "prevent_resize_existing_files": true
      }
    }
  }
}
resize_stylestring#

This key defines how image files are resized prior to upload, using a bounding box defined by width and height options.

Valid values are cover, contain, crop, or stretch:

  • cover keeps aspect ratio and ensures the image covers the bounding box
  • contain keeps aspect ratio and ensures the image fits inside the bounding box
  • crop prompts the user with and interface to select an aspect-ratio-respecting area
  • stretch ignores aspect ratio and resizes the image to the bounding box

This key does not apply to existing images, and does not work if width and height options are not defined.

Defaults to: contain

Allowed values: cover contain stretch crop

Show examplesHide examples

In this example, we have configured an Image Input to resize images using the cover style to ensure images cover the bounding box while maintaining aspect ratio.

Copied to clipboard
_inputs:
  hero_image:
    type: image
    options:
      width: 1200
      height: 600
      resize_style: cover
{
  "_inputs": {
    "hero_image": {
      "type": "image",
      "options": {
        "width": 1200,
        "height": 600,
        "resize_style": "cover"
      }
    }
  }
}
sizesArray<sizes[*]>#

This key defines definitions for creating additional images of different sizes when uploading or selecting existing files.

Show examplesHide examples

In this example, we have configured an Image Input to create additional images of different sizes when uploading or selecting files.

Copied to clipboard
_inputs:
  hero_image:
    type: image
    options:
      sizes:
        - size: 2x
        - size: 3x
{
  "_inputs": {
    "hero_image": {
      "type": "image",
      "options": {
        "sizes": [
          {
            "size": "2x"
          },
          {
            "size": "3x"
          }
        ]
      }
    }
  }
}
widthnumber#

This key defines the width of the bounding box used in the resizing method defined by resize_style.

Examples:
Open in a new tab