options

Description:

This key defines options that are specific to File Inputs.

Appears in:

└── _inputs
    └── *
        └── File Input
            └── options

_inputs
- *
  - File Input
    options

Type:

Object

Properties:

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.

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

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

disable_direct_inputboolean#

This key toggles whether CloudCannon will prevent typing into the Text Input, while still allowing context menu options to change the value.

Setting this key to true will prevent typing into the Text Input.

Defaults to: false

Show examplesHide examples

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

Copied to clipboard

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

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

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

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

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

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

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

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

localestring#

This key defines the locale that CloudCannon uses to determine the number of words or graphemes in this Input, if you have max_words, min_words, max_graphemes, or min_graphemes configured.

max_file_sizenumber#

This key defines the maximum file size in kB that CloudCannon will allow you to upload.

When configured, CloudCannon will prevent you from saving your changes until you select a valid file size, or discard your unsaved changes.

Value can be any positive integer.

This key has no default.

This key is available for File and URL Inputs.

Show examplesHide examples

In this example, we want our team to upload an image using the feature_image Input. This Input limits you to a maximum file size of 750 kB.

Copied to clipboard

_inputs:
  feature_image:
    type: image
    comment: Select the feature image for the banner.
    options:
      max_file_size: 140

{
  "_inputs": {
    "feature_image": {
      "type": "image",
      "comment": "Select the feature image for the banner.",
      "options": {
        "max_file_size": 140
      }
    }
  }
}

max_file_size_messagestring#

This key defines a custom error message that explains why a value has failed the validation criteria from options.max_file_size. This key requires you to define options.max_file_size.

This key has no default.

This key is available for File and URL Inputs.

Show examplesHide examples

In this example, we want our team to upload an image using the feature_image Input. This Input limits you to a maximum file size of 750 kB.

Copied to clipboard

_inputs:
  feature_image:
    type: image
    comment: Select the feature image for the banner.
    options:
      max_file_size: 140
      max_file_size_message: For SEO, keep this under 140kB

{
  "_inputs": {
    "feature_image": {
      "type": "image",
      "comment": "Select the feature image for the banner.",
      "options": {
        "max_file_size": 140,
        "max_file_size_message": "For SEO, keep this under 140kB"
      }
    }
  }
}

max_graphemesnumber#

This key defines the maximum string length, in graphemes, 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.

max_graphemes_messagestring#

This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_graphemes.

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

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

max_wordsnumber#

This key defines the maximum string length, in words, 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.

max_words_messagestring#

This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_words.

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

min_graphemesnumber#

This key defines the minimum string length, in graphemes, 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.

min_graphemes_messagestring#

This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_graphemes.

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

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

min_wordsnumber#

This key defines the minimum string length, in words, 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.

min_words_messagestring#

This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_words.

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

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 ___@___.__"
      }
    }
  }
}

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

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 ___@___.__"
      }
    }
  }
}

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

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

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

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

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:

User Articles

User Guides

User Glossary

Developer Articles

Developer Guides

Developer Reference

`options`

Table of contents