Configure a File input

Last modified: June 19th, 2025

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 File input in the Data Editor, showing a dropdown menu to upload or browse assets.

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:

  1. 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.
  2. 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, a markup file, or any where you configure a Structure.
  3. Identify the _inputs key, or create one at that level of the configuration cascade.
  4. 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.
  5. Add the type key under your input name key, with the value file, document, or image.
  6. (Optional.) Add any other general configuration keys (e.g., label, comment, context) under your input name key.
  7. (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.

cloudcannon.config.yaml
copied
_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.

cloudcannon.config.json
copied
{
  "_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.

data.yml
copied

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.

cloudcannon.config.yaml
copied
_inputs:
  image:
    type: image
    label: Featured Image
    comment: Upload or select an image for this post
    options:
      paths:
        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
cloudcannon.config.json
copied
{
  "_inputs": {
    "image": {
      "type": "image",
      "label": "Featured Image",
      "comment": "Upload or select an image for this post",
      "options": {
        "paths": {
          "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.

paths — Object#

This key enables you to define paths for your Rich Text editors or File inputs. The following nested keys are available:

  • dam_static
  • dam_uploads
  • dam_uploads_filename
  • static
  • uploads
  • uploads_filename
  • uploads_use_relative_paths

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

For more information, please read our documentation on Rich Text editors or File inputs.

paths.dam_static — String#

This key enables you to define the path for the location of statically copied assets for DAM files.

paths.dam_uploads — String#

This key enables you to define the path for the default location of newly uploaded DAM files.

You can use dynamic placeholders for uploads and dam_uploads. For more information, please read our documentation on adjusting file upload paths.

paths.dam_uploads_filename — String#

This key enables you to define the name of a file, after uploading it to a DAM.

paths.static — String#

This key enables you to define the path for the location of statically copied assets.

paths.uploads — String#

This key enables you to define the path for the default location of newly uploaded files.

You can use dynamic placeholders for uploads and dam_uploads. For more information, please read our documentation on adjusting file upload paths.

paths.uploads_filename — String#

This key enables you to define the name of a file, after uploading it.

paths.uploads_use_relative_paths — Boolean#

This key enables you to use a file path relative to the current file when uploading through this input. File inputs in data files or front matter will also use relative file paths when selecting an existing file.

accepts_mime_types — String or array of strings#

This key restricts which file types you are allowed to select or upload through an input. Each File input type has a different default:

  • File: *
  • Image: image/x-icon,image/gif,image/jpeg,image/jpeg,image/png,image/webp,image/bmp,image/svg+xml
  • Document: application/pdf,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document,application/vnd.ms-excel,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,application/vnd.ms-powerpoint,application/vnd.openxmlformats-officedocument.presentationml.presentation

If this key uses a string value, the value format should be a comma-separated (no spaces) list of accepted MIME types. The string * allows any type.

If this key uses an array of values, each item in the array should be a string containing a single accepted MIME type.

allowed_sources — Array#

This key lists which 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.

empty_type — String#

This key determines how CloudCannon handles an empty value. This key does not apply to existing empty values.

Value must be one of the following:

  • string - an empty value for this input will be stored as "".
  • null - an empty value for this input will be stored as a null value (default). This does not apply to TOML files.
_inputs.*.options.required — Boolean#

This key toggles whether CloudCannon requires this Input to have a value. If set to true, CloudCannon 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, Boolean, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

Show exampleHide example

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

cloudcannon.config.yaml
copied
_inputs:
  author:
    type: text
    comment: Enter the name of the author for this blog post.
    options:
      required: true
cloudcannon.config.json
copied
{
  "_inputs": {
    "author": {
      "type": "text",
      "comment": "Enter the name of the author for this blog post.",
      "options": {
        "required": true
      }
    }
  }
}
_inputs.*.options.max_length — Number#

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 exampleHide example

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.

cloudcannon.config.yaml
copied
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      min_length: 25
cloudcannon.config.json
copied
{
  "_inputs": {
    "seo_description": {
      "type": "markdown",
      "comment": "Enter a brief description of this blog.",
      "options": {
        "max_length": 125,
        "min_length": 25
      }
    }
  }
}
_inputs.*.options.min_length — Number#

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 exampleHide example

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.

cloudcannon.config.yaml
copied
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      min_length: 25
cloudcannon.config.json
copied
{
  "_inputs": {
    "seo_description": {
      "type": "markdown",
      "comment": "Enter a brief description of this blog.",
      "options": {
        "max_length": 125,
        "min_length": 25
      }
    }
  }
}
_inputs.*.options.pattern — String#

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.

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 exampleHide example

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

cloudcannon.config.yaml
copied
_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 ___@___.__
cloudcannon.config.json
copied
{
  "_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.*.options.pattern_message — String#

This key defines the message that explains which regular expression an Input will accept. 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 exampleHide example

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

cloudcannon.config.yaml
copied
_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 ___@___.__
cloudcannon.config.json
copied
{
  "_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.*.options.disable_upload_file — Boolean#

This key toggles whether CloudCannon shows the "Upload a new file" option in the "Add URL" dropdown menu on a URL Input or "Add file" dropdown menu on a File Input. When set to true, the "Upload a new file" option is not available.

By default, this key is false (i.e., users can upload files).

Show exampleHide example

In this example, we have a logo Image input where users can only select existing images but cannot upload new ones.

cloudcannon.config.yaml
copied
_inputs:
  logo:
    type: image
    label: Company Logo
    options:
      disable_upload_file: true
cloudcannon.config.json
copied
{
  "_inputs": {
    "logo": {
      "type": "image",
      "label": "Company Logo",
      "options": {
        "disable_upload_file": true
      }
    }
  }
}
_inputs.*.options.disable_direct_input — Boolean#

This key toggles whether you can type in the text field of a File Input or URL Input. When set to true, you cannot manually type or paste values into the input text field.

By default, this key is false (i.e., users can type directly into the input field).

Show exampleHide example

In this example, we have a document File input where users must select files through the file browser and cannot manually type file paths.

cloudcannon.config.yaml
copied
_inputs:
  document:
    type: document
    label: PDF Document
    options:
      disable_direct_input: true
cloudcannon.config.json
copied
{
  "_inputs": {
    "document": {
      "type": "document",
      "label": "PDF Document",
      "options": {
        "disable_direct_input": true
      }
    }
  }
}
_inputs.*.options.disable_upload_file_in_file_browser — Boolean#

This key toggles whether the "Add" button in the top right of the File browser modal is available, after selecting the "Link to existing file" option in the "Add URL" dropdown menu on a URL Input or "Add file" dropdown menu on a File Input. When set to true, the "Link to existing file" option is not available.

By default, this key is false (i.e., users can upload files in the File browser modal).

Show exampleHide example

In this example, we have a background_image Image input where users can upload files using the "Upload a new file" option in the "Add URL" dropdown menu on a URL Input or "Add file" dropdown menu on a File Input, but not from within the File browser modal.

cloudcannon.config.yaml
copied
_inputs:
  background_image:
    type: image
    label: Background Image
    options:
      disable_upload_file_in_file_browser: true
cloudcannon.config.json
copied
{
  "_inputs": {
    "background_image": {
      "type": "image",
      "label": "Background Image",
      "options": {
        "disable_upload_file_in_file_browser": true
      }
    }
  }
}

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

resize_style — String#

This key determines how CloudCannon resizes images prior to uploading them to your repository or DAM. CloudCannon resizes images using a bounding box defined by the width and height options. Defaults to contain, if width and height are defined.

Value must be one of the following:

  • crop — Prompts the user to choose a region of the image that matches the dimensions of the bounding box.
  • cover — Keeps the original aspect ratio of the uploaded image but enlarges the image to match the largest dimension of the bounding box.
  • contain — Keeps the original aspect ratio of the uploaded image but reduces the image to match the smallest dimension of the bounding box.
  • stretch — Ignores the original aspect ratio and resizes the image to match the dimensions of the bounding box.

If either width or height are not defined, the contain, cover and stretch options will not work. For the cropoption, width and height are optional, and control the minimum size and aspect ratio of the crop region.

width — Integer#

This key determines the width of the bounding box CloudCannon uses to resize images prior to upload. Works in conjunction with the resize_style option.

height — Integer#

This key determines the height of the bounding box CloudCannon uses to resize images prior to upload. Works in conjunction with the resize_style option.

mime_type — String#

This key determines what format CloudCannon will convert an image to prior to uploading it. CloudCannon also updates the file extension. Defaults to keeping an image's original MIME type.

Value must be one of:

  • image/jpeg
  • image/png
  • image/webp
expandable — Boolean#

This key determines whether you can expand an image to fit the bounding box when resizing an image prior to upload. Defaults to false. Has no effect if files are not resized.

prevent_resize_existing_files — Boolean#

This key determines whether CloudCannon will prompt you to resize an existing image when you select it through this input. Defaults to false.

When resizing an existing image, CloudCannon will save the resized copy without overwriting the original file.

sizes — Array of objects#

This key determines whether CloudCannon will create additional images of different sizes when uploading or selecting an image through this input. This key has no default.

Each entry in the array contains the following fields:

  • size — Set the dimensions for the additional image file. Value must be a number with the "x" suffix for relative size or "w" suffix for fixed width (e.g., 2x, 3x, 100w, 360w).
  • target — References another input. CloudCannon sets the value of this target input to the file path of the additional image file.

If CloudCannon cannot create an additional image (e.g., the image you uploaded is too small), CloudCannon does not set the value of the target input.

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.
data.yml
copied

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.

Open in a new tab