Configure a File input

Permissions required

Members of all Default Permission Groups, or Custom Permission Groups with the site:file:write permission, can configure inputs in all locations in the configuration cascade. You can limit permission to specific locations in the configuration using file globs.

A File input is an editing interface for file paths, allowing you to upload a file to your repository or DAM, or add links to external files. By configuring your inputs, you can customize the appearance and functionality for a better editing experience.

A screenshot of the Image Input in the Data Editor shows a preview for the selected image file.

These instructions assume that you know what type of File input you want to configure and where in the configuration cascade. For more information, please read our documentation on File inputs, inputs in general, and the configuration cascade.

To configure a File input:

Open your website files in your local development environment, or log in to CloudCannon and select the Site for which you want to configure your input.
Navigate to the location in the configuration cascade where you want to configure your input. This can be the root of your CloudCannon Configuration File, within the collections_config.* key in your CloudCannon Configuration File, a Schema file, the frontmatter of a markup file, or any where you configure a Structure.
Identify the _inputs key, or create one at that level of the configuration cascade.
Add an input name key for your input under the _inputs key (a.k.a., _inputs.*). We recommend naming your input something simple that indicates the function or context.
Add the type key under your input name key, with the value file, document, or image.
(Optional.) Add any other general configuration keys (e.g., label, comment, context) under your input name key.
(Optional.) Add any specific configuration keys under _inputs.*.options (e.g., paths, accepts_mime_types, allowed_sources).

CloudCannon will now apply this input configuration to all markup files that use your input name key, without needing to save your configuration. This allows you to make changes to your input configuration and see those changes affect inputs live.

When you are happy with your input configuration, you must save your input configuration.

Copied to clipboard

_inputs:
  example_css:
    type: file
  download_newsletter:
    type: document
  logo:
    type: image

{
  "_inputs": {
    "example_css": {
      "type": "file"
    },
    "download_newsletter": {
      "type": "document"
    },
    "logo": {
      "type": "image"
    }
  }
}

All inputs are defined under the _inputs key, regardless of where they are in the configuration cascade.

This File input is called example_css.

The value of the type key determines the input type. This is a file input.

This Document input is called download_newsletter.

The value of the type key determines the input type. This is a document File input.

This Image input is called logo.

The value of the type key determines the input type. This is a image File input.

When you add your input key name to a data or markup file, your configured File input will appear in the Data Editor, Visual Editor, or Content Editor.

YAML

Copied to clipboard

example_css: /guides/tutorial-styles.css
download_newsletter: /newsletters/july-2024.pdf
logo: /web-assets/logo.png

Input configuration options#

General configuration options are available for all input types. You can define the label, comment, and context box for your File input, whether it is hidden or disabled, and how CloudCannon should handle configuration at multiple levels of the configuration cascade.

Specific configuration options for File inputs include defining the default path for uploading assets, which MIME types an input will accept, which DAMs you can upload to and browse, and how CloudCannon handles empty values. You can also add input validation to require a value, specify the minimum and maximum value length, maximum file size, or match a regular expression. For inputs that accept images, you can configure how CloudCannon resizes images, MIME type, and whether CloudCannon creates additional images of different sizes when you upload a new asset.

Here is an example of a File input using some of the most commonly used configuration keys.

Copied to clipboard

_inputs:
  image:
    type: image
    label: Featured Image
    comment: Upload or select an image for this post
    options:
      path:
        uploads: images
      accepts_mime_types:
        - image/png
        - image/jpeg
      allowed_sources:
        - site-files
      required: true
      max_file_size: 5242880
      pattern: (?i)\.(jpe?g|png)$
      pattern_message: Please select a JPG or PNG image file

{
  "_inputs": {
    "image": {
      "type": "image",
      "label": "Featured Image",
      "comment": "Upload or select an image for this post",
      "options": {
        "path": {
          "uploads": "images"
        },
        "accepts_mime_types": [
          "image/png",
          "image/jpeg"
        ],
        "allowed_sources": [
          "site-files"
        ],
        "required": true,
        "max_file_size": 5242880,
        "pattern": "(?i)\\.(jpe?g|png)$",
        "pattern_message": "Please select a JPG or PNG image file"
      }
    }
  }
}

For a complete list of configuration keys available for inputs please read our Inputs reference documentation.

These keys configure the appearance and functionality of File inputs in CloudCannon.

options.accepts_mime_typesComma Separated Accepts Mime Types|Array Accepts Mime Types#

This key defines which file types are available to select or upload to this input.

Accepted format is an array or comma-separated string of MIME types.

The special value "*" means any type is accepted.

Appears in: URL Input options, File Input options.

Show examplesHide examples

In this example, we have configured a Image Input to accept only JPEG or PNG files.

Copied to clipboard

_inputs:
  featured_image:
    type: image
    options:
      accepts_mime_types:
        - image/jpeg
        - image/png

{
  "_inputs": {
    "featured_image": {
      "type": "image",
      "options": {
        "accepts_mime_types": [
          "image/jpeg",
          "image/png"
        ]
      }
    }
  }
}

options.allowed_sourcesArray<allowed_sources[*]>#

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

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.

Appears in: Rich Text Input options, URL Input options, File Input options, _editables.content, _editables.block, _editables.image.

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"
        ]
      }
    }
  }
}

options.disable_direct_inputboolean#

This key toggles whether CloudCannon will prevent typing into the text field of a File or URL Input, while still allowing context menu options to change the value.

Setting this key to true will prevent typing into the input text field.

Defaults to: false

Appears in: URL Input options, File Input options.

Show examplesHide examples

In this example, CloudCannon will prevent typing into the URL Input url.

Copied to clipboard

_inputs:
  url:
    type: url
    options:
      disable_direct_input: true

{
  "_inputs": {
    "url": {
      "type": "url",
      "options": {
        "disable_direct_input": true
      }
    }
  }
}

options.disable_upload_fileboolean#

This key toggles whether CloudCannon will disable the context menu option and the drop area for uploading files.

Setting this key to true will disable the context menu option and prevent uploading file through drag-and-drop in a File Input.

Defaults to: false

Appears in: URL Input options, File Input options.

Show examplesHide examples

In this example, CloudCannon will disable the option to upload a file in the context menu and prevent uploading file through drag-and-drop in a File Input.

Copied to clipboard

_inputs:
  image:
    type: image
    options:
      disable_upload_file: true

{
  "_inputs": {
    "image": {
      "type": "image",
      "options": {
        "disable_upload_file": true
      }
    }
  }
}

options.disable_upload_file_in_file_browserboolean#

This key toggles whether CloudCannon will prevent file uploads inside the "Select existing file/image" file browser modal window.

Setting this key to true will prevent file uploads inside the file browser modal window.

Defaults to: false

Appears in: URL Input options, File Input options.

Show examplesHide examples

In this example, CloudCannon will disable the option to upload files inside the file browser modal window.

Copied to clipboard

_inputs:
  image:
    type: file
    options:
      disable_upload_file_in_file_browser: true

{
  "_inputs": {
    "image": {
      "type": "file",
      "options": {
        "disable_upload_file_in_file_browser": true
      }
    }
  }
}

options.empty_typestring#

This key defines how an 'empty' value will be saved. Does not apply to existing empty values.

Defaults to: null

Allowed values: null string

Appears in: Text Input options, Textarea Input options, Code Input options, Color Input options, URL Input options, Select Input options, Rich Text Input options, Date/Datetime Input options, Time Input options, File Input options, Choice Input options.

options.max_lengthnumber#

This key defines the maximum string length, in characters, that CloudCannon will allow in an Input.

When configured, CloudCannon will warn you when an Input value is too long.

If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.

Value can be any non-negative integer.

If this key is set to 0, CloudCannon requires the Input to be empty.

If options.min_length is also configured, this key cannot be a smaller number.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

To use this key in a Select Input, allow_create must be set to true.

Show examplesHide examples

In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input limits you to a maximum of 125 characters.

Copied to clipboard

_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      min_length: 25

{
  "_inputs": {
    "seo_description": {
      "type": "markdown",
      "comment": "Enter a brief description of this blog.",
      "options": {
        "max_length": 125,
        "min_length": 25
      }
    }
  }
}

options.max_length_messagestring#

This key defines a custom error message that explains why a value has failed the validation criteria from options.max_length.

This key requires you to define options.max_length.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

Show examplesHide examples

In this example, we prompt our team to enter a valid number of characters using a custom message.

Copied to clipboard

_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      max_length_message: You are only allowed 125 characters.
      min_length: 25
      min_length_message: Please write more than 25 characters.

{
  "_inputs": {
    "seo_description": {
      "type": "markdown",
      "comment": "Enter a brief description of this blog.",
      "options": {
        "max_length": 125,
        "max_length_message": "You are only allowed 125 characters.",
        "min_length": 25,
        "min_length_message": "Please write more than 25 characters."
      }
    }
  }
}

options.min_lengthnumber#

This key defines the minimum string length, in characters, that CloudCannon will allow in an Input.

When configured, CloudCannon will warn you when an Input value is too short.

If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.

Value can be any positive integer.

If options.max_length is also configured, this key cannot be a greater number.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

To use this key in a Select Input, allow_create must be set to true.

Show examplesHide examples

In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input requires a minimum of 25 characters.

Copied to clipboard

_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      min_length: 25

{
  "_inputs": {
    "seo_description": {
      "type": "markdown",
      "comment": "Enter a brief description of this blog.",
      "options": {
        "max_length": 125,
        "min_length": 25
      }
    }
  }
}

options.min_length_messagestring#

This key defines a custom error message that explains why a value has failed the validation criteria from options.min_length.

This key requires you to define options.min_length.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

Show examplesHide examples

In this example, we prompt our team to enter a valid number of characters using a custom message.

Copied to clipboard

_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      max_length_message: You are only allowed 125 characters.
      min_length: 25
      min_length_message: Please write more than 25 characters.

{
  "_inputs": {
    "seo_description": {
      "type": "markdown",
      "comment": "Enter a brief description of this blog.",
      "options": {
        "max_length": 125,
        "max_length_message": "You are only allowed 125 characters.",
        "min_length": 25,
        "min_length_message": "Please write more than 25 characters."
      }
    }
  }
}

options.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.

Appears in: Rich Text Input options, URL Input options, File Input options, _editables.content, _editables.block, _editables.link, _editables.image, _editables.text.

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/"
      }
    }
  }
}

options.paths.dam_staticstring#

This key defines the path for the location of statically copied assets for DAM files.

Appears in: paths.

Show examplesHide examples

In this example, we have configured the DAM static path for the blog Collection.

Copied to clipboard

collections_config:
  blog:
    paths:
      dam_static: /assets/dam/

{
  "collections_config": {
    "blog": {
      "paths": {
        "dam_static": "/assets/dam/"
      }
    }
  }
}

options.paths.dam_uploadsstring#

This key defines the path for the default location of newly uploaded DAM files.

You can use dynamic placeholders for uploads and dam_uploads.

Appears in: paths.

Show examplesHide examples

In this example, we have configured the DAM uploads path for the blog Collection.

Copied to clipboard

collections_config:
  blog:
    paths:
      dam_uploads: /dam/uploads/blog/

{
  "collections_config": {
    "blog": {
      "paths": {
        "dam_uploads": "/dam/uploads/blog/"
      }
    }
  }
}

options.paths.dam_uploads_filenamestring#

This key defines the path for the name of the uploaded file, when uploading DAM files.

Appears in: paths.

Show examplesHide examples

In this example, we have configured the DAM uploads filename path for the blog Collection.

Copied to clipboard

collections_config:
  blog:
    paths:
      dam_uploads_filename: '{filename|slugify}'

{
  "collections_config": {
    "blog": {
      "paths": {
        "dam_uploads_filename": "{filename|slugify}"
      }
    }
  }
}

options.paths.staticstring#

This key defines the path for the location of statically copied assets.

Appears in: paths.

Show examplesHide examples

In this example, we have configured the static path for the blog Collection.

Copied to clipboard

collections_config:
  blog:
    paths:
      static: /assets/

{
  "collections_config": {
    "blog": {
      "paths": {
        "static": "/assets/"
      }
    }
  }
}

options.paths.uploadsstring#

This key defines the paths for the default location of newly uploaded site files.

You can use dynamic placeholders for uploads and dam_uploads.

Defaults to: uploads

Appears in: paths.

Show examplesHide examples

In this example, we have configured the uploads path for the blog Collection.

Copied to clipboard

collections_config:
  blog:
    paths:
      uploads: /uploads/blog/

{
  "collections_config": {
    "blog": {
      "paths": {
        "uploads": "/uploads/blog/"
      }
    }
  }
}

options.paths.uploads_filenamestring#

This key defines the path for the name of the uploaded file.

Appears in: paths.

Show examplesHide examples

In this example, we have configured the uploads filename path for the blog Collection.

Copied to clipboard

collections_config:
  blog:
    paths:
      uploads_filename: '{filename|slugify}'

{
  "collections_config": {
    "blog": {
      "paths": {
        "uploads_filename": "{filename|slugify}"
      }
    }
  }
}

options.paths.uploads_use_relative_pathboolean#

This key toggles whether CloudCannon will use relative paths instead of absolute paths for uploaded files.

Setting this key to true will make CloudCannon use relative paths for uploaded files, which are relative to the file being edited rather than the repository root.

Defaults to: false

Appears in: paths.

Show examplesHide examples

In this example, we have configured uploads to use relative paths for files uploaded in the Content Editor.

Copied to clipboard

_editables:
  content:
    paths:
      uploads_use_relative_path: true

{
  "_editables": {
    "content": {
      "paths": {
        "uploads_use_relative_path": true
      }
    }
  }
}

options.patternstring#

This key defines a regular expression that the Input value must match.

When configured, CloudCannon will require you to enter a value that matches the REGEX pattern.

If the Input already contains an invalid value, CloudCannon will require you to enter a valid string to save your changes, or discard your unsaved changes.

Value must be a valid REGEX string.

If your REGEX string includes a \ character and CloudCannon Configuration File is a .yml file, use single quotes ' around the string to avoid a build error.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

To use this key in a Select Input, allow_create must be set to true.

Show examplesHide examples

In this example, we want our team to add an email address to the contact_email Input using the correct email format.

Copied to clipboard

_inputs:
  contact_email:
    type: email
    options:
      pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
      pattern_message: Please use the format ___@___.__

{
  "_inputs": {
    "contact_email": {
      "type": "email",
      "options": {
        "pattern": "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",
        "pattern_message": "Please use the format ___@___.__"
      }
    }
  }
}

options.pattern_flagsObject#

This key defines the flags (e.g. case-insensitive searching) for the regular expression set in options.pattern.

Show examplesHide examples

In this example, we have configured pattern flags for a text input to enable case-insensitive searching.

Copied to clipboard

_inputs:
  search_term:
    type: text
    options:
      pattern: ^[a-z]+$
      pattern_flags:
        ignore_case: true

{
  "_inputs": {
    "search_term": {
      "type": "text",
      "options": {
        "pattern": "^[a-z]+$",
        "pattern_flags": {
          "ignore_case": true
        }
      }
    }
  }
}

options.pattern_flags.dot_allboolean#

This key defines the s flag - . matches newline characters.

Defaults to: false

Appears in: pattern_flags.

options.pattern_flags.globalboolean#

This key defines the g flag - Search globally.

Defaults to: false

Appears in: pattern_flags.

options.pattern_flags.ignore_caseboolean#

This key defines the i flag - Case-insensitive.

Defaults to: false

Appears in: pattern_flags.

options.pattern_flags.multilineboolean#

This key defines the m flag - ^ and $ match the start and end of each line rather than the entire string.

Defaults to: false

Appears in: pattern_flags.

options.pattern_flags.unicodeboolean#

This key defines the u flag - Pattern is treated as a sequence of Unicode code points.

Defaults to: false

Appears in: pattern_flags.

options.pattern_flags.unicode_setsboolean#

This key defines the v flag for extended unicode mode.

Defaults to: false

Appears in: pattern_flags.

options.pattern_messagestring#

This key defines a custom error message that explains why a value has failed the validation criteria from options.pattern.

This key requires you to define options.pattern.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

Show examplesHide examples

In this example, we prompt our team to use the correct email format in the contact_email Input using a pattern message.

Copied to clipboard

_inputs:
  contact_email:
    type: email
    options:
      pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
      pattern_message: Please use the format ___@___.__

{
  "_inputs": {
    "contact_email": {
      "type": "email",
      "options": {
        "pattern": "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",
        "pattern_message": "Please use the format ___@___.__"
      }
    }
  }
}

options.requiredboolean#

This key toggles whether CloudCannon requires this Input to have a value.

Setting this key to true will require you to enter a value to save your changes, or discard your unsaved changes.

By default, this key is false (i.e., CloudCannon does not require this Input to have a value).

This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

Defaults to: false

Appears in: Text Input options, Textarea Input options, Code Input options, Color Input options, Number Input options, Range Input options, URL Input options, Select Input options, Rich Text Input options, Date/Datetime Input options, Time Input options, File Input options, Multiselect Input options, Choice Input options, Multichoice Input options, Object Input options, Array Input options.

Show examplesHide examples

In this example, we want to require our team to enter an author value for markup files with this Input.

Copied to clipboard

_inputs:
  author:
    type: text
    comment: Enter the name of the author for this blog post.
    options:
      required: true

{
  "_inputs": {
    "author": {
      "type": "text",
      "comment": "Enter the name of the author for this blog post.",
      "options": {
        "required": true
      }
    }
  }
}

options.required_messagestring#

This key defines a custom error message that explains why a value has failed the validation criteria from options.required.

This key requires you to define options.required.

This key has no default.

This key is available for Array, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

Show examplesHide examples

In this example, we prompt our team to enter an Input value using a required message.

Copied to clipboard

_inputs:
  author:
    type: text
    comment: Enter the name of the author for this blog post.
    options:
      required: true
      required_message: You are not allowed to leave this blank.

{
  "_inputs": {
    "author": {
      "type": "text",
      "comment": "Enter the name of the author for this blog post.",
      "options": {
        "required": true,
        "required_message": "You are not allowed to leave this blank."
      }
    }
  }
}

If the input accepts images, the following options are also available:

options.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

Appears in: Rich Text Input options, URL Input options, File Input options, _editables.content, _editables.block, _editables.image.

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
      }
    }
  }
}

options.heightnumber#

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

Appears in: Rich Text Input options, URL Input options, File Input options, _editables.content, _editables.block, _editables.image.

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"
      }
    }
  }
}

options.mime_typestring#

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

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

Appears in: Rich Text Input options, URL Input options, File Input options, _editables.content, _editables.block, _editables.image.

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"
      }
    }
  }
}

options.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

Appears in: Rich Text Input options, URL Input options, File Input options, _editables.content, _editables.block, _editables.image.

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
      }
    }
  }
}

options.resize_stylestring#

This key defines how image files are resized prior to upload, using a bounding box defined by width and height options (these optionas are required). This key applies to existing images unless prevent_resize_existing_files is set. Setting this key to 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 an interface to select an aspect-ratio-respecting area, and stretch ignores aspect ratio and resizes the image to the bounding box.

Defaults to: contain

Allowed values: cover contain stretch crop

Appears in: Rich Text Input options, URL Input options, File Input options, _editables.content, _editables.block, _editables.image.

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"
      }
    }
  }
}

options.sizesArray<sizes[*]>#

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

Appears in: Rich Text Input options, URL Input options, File Input options, _editables.content, _editables.block, _editables.image.

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"
          }
        ]
      }
    }
  }
}

options.sizes[*]Object#

This key represents an individual size definition in the options.sizes array for Image Inputs.

The value is an object that can contain size and target properties.

Appears in: sizes.

Show examplesHide examples

In this example, we have configured a size definition for an Image Input.

Copied to clipboard

_inputs:
  hero_image:
    type: image
    options:
      sizes:
        - size: 2x
          target: hero_image_2x

{
  "_inputs": {
    "hero_image": {
      "type": "image",
      "options": {
        "sizes": [
          {
            "size": "2x",
            "target": "hero_image_2x"
          }
        ]
      }
    }
  }
}

sizes[*].sizestring Required#

This key defines a number suffixed with "x" (relative size) or "w" (fixed width) for setting the dimensions of the image (e.g. 2x, 3x, 100w, 360w).

Appears in: sizes[*].

Show examplesHide examples

In this example, we have configured a size definition for an Image Input to create a 2x relative size image.

Copied to clipboard

_inputs:
  hero_image:
    type: image
    options:
      sizes:
        - size: 2x

{
  "_inputs": {
    "hero_image": {
      "type": "image",
      "options": {
        "sizes": [
          {
            "size": "2x"
          }
        ]
      }
    }
  }
}

sizes[*].targetstring#

This key defines a reference to another input that is given the path to this additional image file.

Appears in: sizes[*].

options.widthnumber#

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

Appears in: Rich Text Input options, URL Input options, File Input options, _editables.content, _editables.block, _editables.image.

Valid values#

Here are some examples of valid values for the key file. These work for File, Document, and Image inputs.

Empty/null value:

file:

Any valid string (quoted or unquoted):

file: ""
file: ''
file: path/to/file.ext
file: "path/to/file.ext"
file: 'path/to/file.ext'

Any valid string:

file = ""
file = ''
file = "path/to/file.ext"
file = 'path/to/file.ext'

Null value:

"file": null

Any valid string:

"file": ""
"file": "path/to/file.ext"

Unconfigured File inputs#

In some cases, CloudCannon can still detect a File input even if you have not configured it.

CloudCannon will interpret any unconfigured input with the key name:

path, or that ends in _path, as a File input.
document or document_path, or that ends in _document or _document_path, as a Document input.
image or image_path, or that ends in _image or _image_path, as an Image input.

YAML

Copied to clipboard

background_image: /images/forest.jpeg

This behavior is convenient if you have simple inputs or do not want to configure inputs. It is also beneficial for new websites on CloudCannon where you have yet to create any CloudCannon-specific configuration.

We recommend configuring your inputs for greater control over their functionality and appearance.

User Articles

User Guides

User Glossary

Developer Articles

Developer Guides

Developer Reference

Configure a File input

On this page

Input configuration options#

Valid values#

Unconfigured File inputs#

Related Resources

Configure a File input

On this page

Input configuration options#

Valid values#

Unconfigured File inputs#

Related Resources

What are inputs?

What is a File input?

What is the Data Editor?