A files select field that allows to select one or multiple related files
The files field allows you to select one or more files.
|default||–||Sets the file(s), which are selected by default when a new page is created|
|empty||–||The placeholder text if none have been selected yet|
|help||–||Optional help text below the field|
|image||–||Image settings for each item|
||–||Info text for each item|
|label||–||The field label can be set as string or associative array with translations|
||Changes the layout of the selected files. Available layouts:
||Whether each item should be clickable|
||–||The maximum number of allowed selected|
||–||The minimum number of required selected|
||–||Query for the items to be included in the picker|
||Enable/disable the search field in the picker|
||Layout size for cards:
||–||Main text for each item|
||Sets the upload options for linked files (since 3.2.0)|
|when||–||Conditions when the field will be shown (since 3.1.0)|
||The width of the field in the field grid. Available widths:
Limit the number of files
Min and max files
You can set the minimum/maximum number of files that can be selected:
Multiple or single mode
If you only want to select a single file, set
multiple mode to
false (default is
You can switch between
cards layout. Default is
query option let's you limit the set of files to be included. When not set, it defaults to all files of the current page.
Limit the set to images
You can use all file types available in Kirby here (
Querying files from other pages
You can get as complex as you like, e.g. get all images of all children of the
photography page that use the
You can find more example how you can use the query language in the guide.
Apart from showing no image, all image options only apply in card layout, not in list layout.
Whether or not the image will cover the available space.
A freely selectable image ratio
Set an image background.
Set the image options to false if you don't want to show an image but an icon instead:
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).
You can set the
uploads property to
false to prevent file uploads:
Destination and template
By default all files will be uploaded to the current page and without a predefined template. With the additional options you can fetch files from anywhere and upload them to a specific page. You can also control which file template should be assigned by default:
If you want to upload to the current page and only assign a template, you can directly assign it to the
Restricting uploads to certain file types
If you want to restrict what types of files can be uploaded to the given destination, assign a file template using the
uploads property. In your file template, set the
accept option. See the docs about file blueprints.
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
The files picker shows a search field by default. If you want to remove it, you can switch it off with the
How to use in templates/snippets
To convert a single file to a file object, use the
To convert multiple files to a files collection, use the