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

Property Type Default Description

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


The placeholder text if none have been selected yet


Optional help text below the field


Image settings for each item

info string

Info text for each item


The field label can be set as string or associative array with translations

layout string list

Changes the layout of the selected files. Available layouts: list, cards

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)


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


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

Since 3.2.0

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.


Since 3.3.0

Options in the pages 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: pages
    label: Select an item
    limit: 10
Since 3.3.0

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

    type: pages
    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 ?>