Skip to content

Kirby 3.7.5


A files select field that allows to select one or multiple related files

The files field allows you to select one or more files.


    label: Downloads
    type: files

Field properties

Name Type Default Description
default Sets the file(s), which are selected by default when a new page is created
disabled bool If true, the field is no longer editable and will not be saved
empty The placeholder text if none have been selected yet
help Optional help text below the field
image Image settings for each item
info string Info text for each item
label The field label can be set as string or associative array with translations
layout string list Changes the layout of the selected entries.
link bool true Whether each item should be clickable
max int The maximum number of allowed selected
min int The minimum number of required selected
multiple bool true If false, only a single one can be selected
query string Query for the items to be included in the picker
required bool 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 or huge
text string 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 [] Sets the upload options for linked files (since 3.2.0)
when Conditions when the field will be shown (since 3.1.0)
width string 1/1 The width of the field in the field grid. Available widths: 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:

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

    label: Select files...
    type: files
    multiple: false


You can switch between list and cards layout. Default is list layout.

    label: Select files...
    type: files
    layout: cards

Querying files

The 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

  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 of all children of the photography page that use the cover template:

  type: files
  query: site.find('photography').children.images.filterBy('template', 'cover')

You can find more example how you can use the query language in the guide.

Image options

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.
Options: true, false (default)

  cover: true


A freely selectable image ratio

  ratio: 16/9


Set an image background.
Options: pattern (default), black, white

  cover: true
  ratio: 1/1
  back: black

No image

Set the image options to false if you don't want to show an image but an icon instead:

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 set the uploads property to false to prevent file uploads:

  type: files
  uploads: false

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:

  type: files
    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:

  type: files
  uploads: files-upload

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 20.

    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:

    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() method:

<?php if($image = $page->cover()->toFile()): ?>
  <img src="<?= $image->url() ?>" alt="">
<?php endif ?>

Multiple files

To convert multiple files to a files collection, use the toFiles() method:

$images =  $page->gallery()->toFiles();
foreach($images as $image): ?>
  <img src="<?= $image->url() ?>" alt="">
<?php endforeach ?>