Files

The files field is basically a select/multiselect field specialized to allow you to select one or more files out of a given set of options. A reference to the selected file(s) is stored in the content file of the respective model (page, user, file). A files field also allows you to upload files (not, however to delete or otherwise manipulate files, see also files section).

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 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`, `huge`, `full`
store	`string`	`uuid`	Whether to store UUID or ID in the content file of the model
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 layouts. Default is list layout.

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

Querying files

The query option lets you limit the set of files that can 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 from 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 examples of how you can use the query language in the guide.

Image options

Apart from showing no image, any image options you use will only apply to the 'card' layout, but not to the 'list' layout.

`ratio`

A freely selectable image aspect ratio for various image styles such as movie trailers, movie posters, or simply portrait, landscape, square, etc.

image:
  ratio: 16/9

`cover`

Whether or not the image will fill (cover) the available image space and not show banding for images that don't match your chosen image aspect ratio.
Options: true, false (default)

image:
  cover: true

`back`

Set an image background behind the image, which will show if cover is not set to true as explained above.
Options: pattern (default), black, white

image:
  cover: true
  ratio: 1/1
  back: black

No image

Don't want to see an image preview? Set the image options to false if you don't want to show an image, which reveals 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 alternatively set the uploads property to false to prevent any file uploads:

gallery:
  type: files
  uploads: false

Destination and template

By default, all files will be uploaded to the current page without any predefined template. But with the additional options, you can fetch files from anywhere, upload them to a specific page, or even 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

To restrict what types of files can be uploaded to the given destination, assign a file template using the uploads property, and in your file template, set the accept option. For more information see the docs about file blueprints.

Supported file types

By default, Kirby supports several files types.

To upload additional file types, you could register new file types with the fileTypes extension in a plugin.

Pagination

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

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 work with or reference multiple files, create the group of files using the toFiles() method:

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