Files

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

Example

fields:
  downloads:
    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 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)
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:

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

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

Layout

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

fields:
  downloads:
    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

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

gallery:
  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.

`cover`

Whether or not the image will cover the available space.
Options: true, false (default)

image:
  cover: true

`ratio`

A freely selectable image ratio

image:
  ratio: 16/9

`back`

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

image:
  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

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:

gallery:
  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:

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:

gallery:
  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.

Pagination

Since 3.3.0

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

Search

Since 3.3.0

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

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