--- url: /en/docs/fields/file.md description: >- Upload, manage, and reference files in Sveltia CMS with multiple file type support. --- # File Field The File field type allows users to upload and manage files within the CMS. ::: tip Alternative for images If you need to limit uploads to images only, consider using the [Image](/en/docs/fields/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](/en/docs/media/internal) is enabled). * [Subfolders](/en/docs/ui/asset-library#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](/en/docs/media#external-storage) if configured. * Integration with [stock photo providers](/en/docs/integrations/stock-photos) 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`](#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](/en/docs/media/internal#using-entry-relative-folders), folders whose path contains a template tag such as `{{slug}}`, [external media storage providers](/en/docs/media#external-storage) 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. ::: tip 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](/en/docs/security#setting-up-content-security-policy) 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`](/en/docs/media#slugification-of-filenames) media storage option. To rename uploaded files automatically, for example after the entry slug, use the [`filename_template`](/en/docs/media#renaming-uploaded-files) 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`](/en/docs/fields#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](/en/docs/fields#common-options), the File field supports the following options: ### Required Options #### `widget` * **Type**: `string` * **Default**: `string` Must be set to `file`. ### Optional Options ::: warning 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](https://gohugo.io/content-management/shortcodes/) or a component that renders all the images in a folder as a gallery, for example. See [Selecting a Folder](#selecting-a-folder) for how it works. This option is compatible with [Static CMS](https://staticjscms.netlify.app/docs/widget-file). #### `accept` * **Type**: `string` * **Default**: `undefined` A comma-separated list of allowed file types ([MIME types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types/Common_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](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/accept) 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](/en/docs/media#heic-photos) 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](/en/docs/media#configuration) 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](/en/docs/media/internal) 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](/en/docs/media#configuration) for details. #### `media_libraries` * **Type**: `object` * **Default**: `undefined` Field-level [media storage provider](/en/docs/media#configuration) 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](/en/docs/media/internal#disabling-internal-media-storage-for-a-field) by setting the `default` library to `false`. See the field-level configuration sections of each provider, such as [Cloudinary](/en/docs/media/cloudinary#field-level-configuration) and [Uploadcare](/en/docs/media/uploadcare#field-level-configuration), 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](/en/docs/media/internal#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](/en/docs/media/internal#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. ::: code-group ```yaml [YAML] - name: document label: Document widget: file ``` ```toml [TOML] [[fields]] name = "document" label = "Document" widget = "file" ``` ```json [JSON] { "fields": [ { "name": "document", "label": "Document", "widget": "file" } ] } ``` ```js [JavaScript] { fields: [ { name: 'document', label: 'Document', widget: 'file', }, ], } ``` ::: Output example: ::: code-group ```yaml [YAML] document: /uploads/sample.pdf ``` ```toml [TOML] document = "/uploads/sample.pdf" ``` ```json [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. ::: code-group ```yaml [YAML] - name: flyers label: Flyers widget: file multiple: true min: 1 max: 5 accept: application/pdf,.pdf ``` ```toml [TOML] [[fields]] name = "flyers" label = "Flyers" widget = "file" multiple = true min = 1 max = 5 accept = "application/pdf,.pdf" ``` ```json [JSON] { "fields": [ { "name": "flyers", "label": "Flyers", "widget": "file", "multiple": true, "min": 1, "max": 5, "accept": "application/pdf,.pdf" } ] } ``` ```js [JavaScript] { fields: [ { name: 'flyers', label: 'Flyers', widget: 'file', multiple: true, min: 1, max: 5, accept: 'application/pdf,.pdf', }, ], } ``` ::: Output example: ::: code-group ```yaml [YAML] flyers: - /uploads/flyer1.pdf - /uploads/flyer2.pdf ``` ```toml [TOML] flyers = ["/uploads/flyer1.pdf", "/uploads/flyer2.pdf"] ``` ```json [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. ::: code-group ```yaml [YAML] - name: gallery label: Gallery widget: file select_folder: true ``` ```toml [TOML] [[fields]] name = "gallery" label = "Gallery" widget = "file" select_folder = true ``` ```json [JSON] { "fields": [ { "name": "gallery", "label": "Gallery", "widget": "file", "select_folder": true } ] } ``` ```js [JavaScript] { fields: [ { name: 'gallery', label: 'Gallery', widget: 'file', select_folder: true, }, ], } ``` ::: Output example: ::: code-group ```yaml [YAML] gallery: /uploads/gallery/2024 ``` ```toml [TOML] gallery = "/uploads/gallery/2024" ``` ```json [JSON] { "gallery": "/uploads/gallery/2024" } ``` :::