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 is 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).
• 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.

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

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

Preview

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

CSP Settings

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. 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 internal media storage 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 URL(s) must match the specified regular expression pattern.

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.

multiple

• Type: boolean
• Default: false

Whether to allow uploading or selecting multiple files.

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.

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,.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. File field has no default restriction.

media_library

media_libraries

media_folder

public_folder

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