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 Required Default Description
default mixed 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 mixed The placeholder text if no pages have been selected yet
help mixed Optional help text below the field
image array Image settings for each item
info string Info text
label mixed 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`
max int Maximum number of allowed files
min int Minimum number of required files
multiple bool true If false, only a single file can be selected
query string Query for the files to be included
required bool If true, the field has to be filled in correctly to be saved.
size string Layout size for cards: `tiny`, `small`, `medium`, `large` or `huge`
text string {{ file.filename }} Main text
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.
when mixed Conditions when the field will be shown
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

Limits for the number of 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 card 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.

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 ?>