File Field

The File field type allows users to upload and manage files within the CMS.

Alternative for images

If you need to limit uploads to images only, consider using the Image field type instead.

User Interface

Editor

A large upload button is displayed for the File field. When it’s clicked, a file selection dialog with the following features appears:

• Tabs to select files from different sources: field assets, entry assets, file assets, collection assets, and global assets (if the internal media storage is enabled).
• Subfolders of a repository folder are listed ahead of its files, and can be opened with a click or the Enter key to browse them, with a breadcrumb leading back. The arrow keys move between the subfolders, like between the files. A file uploaded while browsing a subfolder is saved there. A new folder can be created from the dialog, too.
• An option to upload new files by dragging and dropping them into the dialog or by selecting them from the file system.
• An option to enter a URL to select a file from an external source (if choose_url option is enabled).
• Integration with external media storage providers if configured.
• Integration with stock photo providers for easy selection of free images (for Image fields only).
• File type filtering based on the accept option.
• A search bar to quickly find existing assets.

If the multiple option is enabled, users can select multiple files at once. Uploaded files are displayed as a list with options to remove or replace each file.

Files in a multiple File or Image field can be reordered using the drag handle to the left of each one. With the handle focused, the Up and Down arrow keys move a file one position, while Home and End send it to the start or end of the list. On a touch screen, Move Up and Move Down buttons are shown in place of the handle, because drag and drop requires a mouse.

Users can paste an image from the clipboard directly into a File or Image field by clicking the Paste button or using the keyboard shortcut (Ctrl+V or Cmd+V). This works on both desktop and mobile devices.

On desktop, users can drag and drop file(s) directly onto the field to attach them without opening the file selection dialog.

Unsaved files can be renamed.

The CMS prevents the same file from being uploaded twice. It compares the hashes and selects an existing asset instead.

Selecting a Folder

With the select_folder option, the field takes a folder instead of a file. The dialog then becomes a Select Folder dialog that lists the subfolders alone, and works like a file manager:

• A click or the Space key selects a subfolder, and a double click or the Enter key opens it. The arrow keys move between the subfolders.
• The folder being browsed is selected when no subfolder is. The path to be saved is shown at the bottom of the dialog.
• If the multiple option is also enabled, several folders can be selected at once, including from different parent folders: the selection is kept while the user browses.
• A new folder can be created from the dialog, as usual.

Only repository folders with a fixed path can be browsed. Entry-relative folders, folders whose path contains a template tag such as {{slug}}, external media storage providers and the URL input are not available, and files can’t be uploaded, dropped or pasted.

Preview

A list of uploaded file names with links to access each file. For images, a thumbnail preview is shown.

CSP

If your site uses a Content Security Policy (CSP), you may need to update it to display external images properly. See the CSP documentation for more details.

Data Type

A string representing the URL or path to a file, or the public path to a folder if the select_folder option is enabled. If multiple option is enabled, it will be an array of strings.

If the required option is set to false and the field is left empty, the value will be an empty string or an empty array, depending on whether multiple is enabled.

By default, Sveltia CMS does not slugify uploaded filenames. If your site generator expects hyphenated filenames, you can enable the slugify_filename media storage option. To rename uploaded files automatically, for example after the entry slug, use the filename_template option.

Data Validation

• If the required option is set to true, at least one file must be selected.
• If the multiple option is enabled, the number of selected files must be between the min and max limits, if specified.
• The selected file(s) must match the allowed file types specified in the accept option, if provided.
• If the pattern option is provided, the file path or URL must match the regular expression. A file just uploaded is tested by its name until the entry is saved. If the multiple option is enabled, the paths or URLs joined with commas, e.g. /uploads/a.jpg,/uploads/b.jpg, must match instead: as with Decap CMS, the pattern is tested against all the files rather than against each one. A pattern like \.pdf$ would therefore only check the last file; use ^[^,]+\.pdf(,[^,]+\.pdf)*$ to accept PDF files only. The pattern is not tested while no file is selected.

Options

In addition to the common field options, the File field supports the following options:

Required Options

widget

• Type: string
• Default: string

Must be set to file.

Optional Options

Breaking change from Netlify/Decap CMS

Sveltia CMS does not support the allow_multiple option. It’s a confusing option that defaults to true, and there is a separate option called media_library.config.multiple. We have added the new multiple option instead, which is more intuitive and works with all media storage providers.

default

• Type: string or array of strings
• Default: '' or []

The default value for the field. Should be a string for single file upload or an array of strings for multiple file uploads. If the multiple option is set on the field, a value of the other shape is reported as a config validation error on the login screen.

multiple

• Type: boolean
• Default: false

Whether to allow uploading or selecting multiple files.

For backward compatibility with Netlify/Decap CMS, if this option is not set, the multiple option in the media storage config is used as a fallback: first media_libraries.*.config.multiple or media_library.config.multiple on the field, then the same options at the top level. Using the multiple option on the field is recommended.

min

• Type: integer
• Default: 0

The minimum number of files required. This enables validation to ensure that users upload or select at least this many files. Ignored if multiple is set to false.

max

• Type: integer
• Default: Infinity

The maximum number of files allowed. This enables validation to prevent users from uploading or selecting more than this many files. Ignored if multiple is set to false.

choose_url

• Type: boolean
• Default: true

Whether to show the option to choose a file by URL instead of uploading/selecting from the media storage.

select_folder

• Type: boolean
• Default: false

Whether to select a folder instead of a file. The public path of the selected folder, such as /uploads/gallery, is saved as the field value. This is useful for a Hugo shortcode or a component that renders all the images in a folder as a gallery, for example. See Selecting a Folder for how it works. This option is compatible with Static CMS.

accept

• Type: string
• Default: undefined

A comma-separated list of allowed file types (MIME types or file extensions) for upload. For example, to allow only PDF files, set this option to application/pdf or .pdf. To allow only image files, set it to image/*. If not specified, all file types are allowed. See the accept attribute documentation on MDN for more details.

Image field only accepts AVIF, GIF, JPEG, PNG, WebP or SVG images by default. Other image formats like BMP, HEIC, JPEG XL, PSD, TIFF are excluded, with one exception: HEIC photos are accepted when HEIC conversion is enabled as part of image optimization. File field has no default restriction.

media_library

• Type: object
• Default: undefined

Legacy option from Netlify/Decap CMS to configure a single media storage provider for this field. Its options are merged over those of the top-level media_library option. It applies to the provider set with its own name; without a name, it applies to the provider named in the top-level media_library option, or to the internal media storage if there is none. In the latter case, media_library.config.max_file_size limits the upload size for the field. Supported for backward compatibility only; use media_libraries for new configurations. See the media storage configuration for details.

media_libraries

• Type: object
• Default: undefined

Field-level media storage provider settings, such as the provider-specific config or the max_file_size limit, that override the top-level media_libraries option for this field. Each provider’s settings, including those of the internal media storage (default), are merged over the same provider’s top-level settings, and so is a nested object such as config, key by key, so only the options that differ need to be set. The merge is only one level deep, and the shared all options are merged shallowly, so a transformations map set here replaces the top-level one as a whole. Providers not defined here fall back to the top-level configuration. This option can also be used to disable the internal media storage for the field by setting the default library to false. See the field-level configuration sections of each provider, such as Cloudinary and Uploadcare, for examples.

media_folder

• Type: string
• Default: undefined

The folder in the repository where files uploaded to this field will be stored, overriding the top-level and collection-level media_folder options. Must start with a slash (/) to indicate an absolute path from the root of the repository, or be an empty string or subfolder name to use entry-relative paths. See the field-level configuration of the internal media storage for details and examples.

public_folder

• Type: string
• Default: undefined

The public URL path that corresponds to the field-level media_folder option, overriding the top-level and collection-level public_folder options. If not specified, it defaults to the value of the field-level media_folder. See the field-level configuration of the internal media storage for details and examples.

Examples

Basic File Field

This example demonstrates a basic File field that allows users to upload or select a single file.

YAML

- name: document
  label: Document
  widget: file

TOML

[[fields]]
name = "document"
label = "Document"
widget = "file"

JSON

{
  "fields": [
    {
      "name": "document",
      "label": "Document",
      "widget": "file"
    }
  ]
}

JavaScript

{
  fields: [
    {
      name: 'document',
      label: 'Document',
      widget: 'file',
    },
  ],
}

Output example:

YAML

document: /uploads/sample.pdf

TOML

document = "/uploads/sample.pdf"

JSON

{
  "document": "/uploads/sample.pdf"
}

Multiple File Uploads with Restrictions

This example shows a File field configured to allow multiple file uploads with minimum and maximum limits.

YAML

- name: flyers
  label: Flyers
  widget: file
  multiple: true
  min: 1
  max: 5
  accept: application/pdf,.pdf

TOML

[[fields]]
name = "flyers"
label = "Flyers"
widget = "file"
multiple = true
min = 1
max = 5
accept = "application/pdf,.pdf"

JSON

{
  "fields": [
    {
      "name": "flyers",
      "label": "Flyers",
      "widget": "file",
      "multiple": true,
      "min": 1,
      "max": 5,
      "accept": "application/pdf,.pdf"
    }
  ]
}

JavaScript

{
  fields: [
    {
      name: 'flyers',
      label: 'Flyers',
      widget: 'file',
      multiple: true,
      min: 1,
      max: 5,
      accept: 'application/pdf,.pdf',
    },
  ],
}

Output example:

YAML

flyers:
  - /uploads/flyer1.pdf
  - /uploads/flyer2.pdf

TOML

flyers = ["/uploads/flyer1.pdf", "/uploads/flyer2.pdf"]

JSON

{
  "flyers": ["/uploads/flyer1.pdf", "/uploads/flyer2.pdf"]
}

Folder Selection

This example shows a File field that takes a folder instead of a file, such as a folder of images to be displayed as a gallery.

YAML

- name: gallery
  label: Gallery
  widget: file
  select_folder: true

TOML

[[fields]]
name = "gallery"
label = "Gallery"
widget = "file"
select_folder = true

JSON

{
  "fields": [
    {
      "name": "gallery",
      "label": "Gallery",
      "widget": "file",
      "select_folder": true
    }
  ]
}

JavaScript

{
  fields: [
    {
      name: 'gallery',
      label: 'Gallery',
      widget: 'file',
      select_folder: true,
    },
  ],
}

Output example:

YAML

gallery: /uploads/gallery/2024

TOML

gallery = "/uploads/gallery/2024"

JSON

{
  "gallery": "/uploads/gallery/2024"
}