# Files A files select field that allows you to select one or more files out of a given set. A reference to this file is stored in the content file. **** - Read more: - Source: **** The files field is basically a select/multiselect field specialized to allow you to select one or more files out of a given set of options. A reference to the selected file(s) is stored in the content file of the respective model (page, user, file). A files field also allows you to upload files (not, however to delete or otherwise manipulate files, see also files section).
## Example ```yaml fields: downloads: label: Downloads type: files ``` ## Field properties
Name Type Default Description
default mixed null Sets the file(s), which are selected by default when a new page is created
disabled bool null If true, the field is no longer editable and will not be saved
empty mixed null The placeholder text if none have been selected yet
help mixed null Optional help text below the field
image mixed null Image settings for each item
info string null Info text for each item
label mixed null The field label can be set as string or associative array with translations
layout string 'list' Changes the layout of the selected entries. Available layouts: list, cardlets, cards
link bool true Whether each item should be clickable
max int null The maximum number of allowed selected
min int null The minimum number of required selected
multiple bool true If false, only a single one can be selected
query string null Query for the items to be included in the picker
required bool null If true, the field has to be filled in correctly to be saved.
search bool true Enable/disable the search field in the picker
size string 'auto' Layout size for cards: tiny, small, medium, large, huge, full
store string 'uuid' Whether to store UUID or ID in the content file of the model
text string null Main text for each item
translate bool true If false, the field will be disabled in non-default languages and cannot be translated. This is only relevant in multi-language setups.
uploads mixed [ ] Sets the upload options for linked files (since 3.2.0)
when mixed null Conditions when the field will be shown (since 3.1.0)
width string '1/1' The width of the field in the field grid, e.g. 1/1, 1/2, 1/3, 1/4, 2/3, 3/4
## Limit the number of files ### Min and max files You can set the minimum/maximum number of files that can be selected: ```yaml fields: downloads: label: Select files... type: files min: 1 max: 3 ``` ### Multiple or single mode If you only want to select a single file, set `multiple` mode to `false` (default is `true`). ```yaml fields: downloads: label: Select files... type: files multiple: false ``` ## Layout You can switch between `list` and `cards` layouts. Default is `list` layout. ```yaml fields: downloads: label: Select files... type: files layout: cards ``` ## Querying files The `query` option lets you limit the set of files that can be included. When not set, it defaults to all files of the current page. ### Limit the set to images ```yaml gallery: type: files query: page.images ``` You can use all file types available in Kirby here (`images`, `documents`, `videos`, `audio`, and `code`). ### Querying files from other pages You can get as complex as you like, e.g. get all images from all children of the `photography` page that use the `cover` template: ```yaml gallery: type: files query: site.find('photography').children.images.filterBy('template', 'cover') ``` You can find more examples of how you can use the query language in the guide. ## Image options Apart from showing no image, any image options you use will only apply to the 'card' layout, but not to the 'list' layout. ### `ratio` A freely selectable image aspect ratio for various image styles such as movie trailers, movie posters, or simply portrait, landscape, square, etc. ```yaml image: ratio: 16/9 ``` ### `cover` Whether or not the image will fill (cover) the available image space and not show banding for images that don't match your chosen image aspect ratio. Options: `true`, `false (default)` ```yaml image: cover: true ``` ### `back` Set an image background behind the image, which will show if cover is not set to true as explained above. Options: `pattern (default)`, `black`, `white` ```yaml image: cover: true ratio: 1/1 back: black ``` ### No image Don't want to see an image preview? Set the image options to `false` if you don't want to show an image, which reveals an icon instead: ```yml image: false ``` ## Upload options By default, the files field allows you to upload files. You can define the `Add` button behavior with the `uploads` option: When clicking on the `Add` button, you can either select a file and/or upload a file (which is then automatically selected). ### Prevent uploading You can alternatively set the `uploads` property to `false` to prevent any file uploads: ```yaml gallery: type: files uploads: false ``` ### Destination and template By default, all files will be uploaded to the current page without any predefined template. But with the additional options, you can fetch files from anywhere, upload them to a specific page, or even control which file template should be assigned by default: ```yaml gallery: type: files uploads: parent: site template: files-upload ``` If you want to upload to the current page and only assign a template, you can directly assign it to the `uploads` property: ```yaml gallery: type: files uploads: files-upload ``` ### Restricting uploads to certain file types To restrict what types of files can be uploaded to the given destination, assign a file template using the `uploads` property, and in your file template, set the `accept` option. For more information see the docs about file blueprints. #### Supported file types By default, Kirby supports several files types. To upload additional file types, you could register new file types with the `fileTypes` extension in a plugin.

Pagination

Options in the files picker are paginated. You can set the number of items per pagination page in the picker using the limit property. The default setting is 20.

fields:
  files:
    type: files
    label: Select an item
    limit: 10

The files picker shows a search field by default. If you want to remove it, you can switch it off with the search option:

fields:
  files:
    type: files
    label: Select an item
    search: false
## How to use in templates/snippets ### Single file To convert a single file to a file object, use the [`toFile()`](/docs/reference/templates/field-methods/to-file) method: ```php cover()->toFile()): ?> ``` ### Multiple files To work with or reference multiple files, create the group of files using the [`toFiles()`](/docs/reference/templates/field-methods/to-files) method: ```php gallery()->toFiles(); foreach($images as $image): ?> ```