How to add custom fields to files


Hi together,

is there a possibility to add custom fields like a file description or something else?

This would be also awesome for SEO reasons. Then you could add custom titles and alternative texts to an image for example.

Are there any ways to implement such fields.

Multiple files list on a content

Check this out: :smile:


Custom fields for files are defined in the blueprints:


Thanks, i completly overlooked that. :slight_smile:


Thanks! Maybe You can tell, how can I access those custom text fields?
Looking at cheat sheets under $file …
in cheat sheet listed commands works, for example:

‘text’ => (string)$image->filename()

trying similar, but this dosnt work:

‘text’ => (string)$image->text()
’text’ => (string)$image->fields()->text()

p.s. trying to add file custom fields for exporting as JSON


Let’s assume you have defined a custom field “caption”, then you can access the value of this field with:

    $image = $page->images()->first();
    $caption = $image->caption();
    echo $caption;


Thanx! But it is not working for me, because Im trying to get file text in a bit different approach.

I am trying to add file textfield with other image data (like height, width etc), You can see in this example:


You can use $image->caption()->toString()


Thanks! My bad (overlooked string in the huge amount of JSON data), it works both ways:


and also



One important thing though - if I only want a “Alternative Text” text field, or a “Featured Image ?” toggle field, to only show up for certain file types, in this case images -that isn’t possible right? :grin:


Not that I know of, but that would be good feature, sth. like:

  - image
        label: Title
        type: text
        label: Alt Text
        type: text
  - document  
        label: Title
        type: text

Different file fields for different file types

Yeah exactly @texnixe - but there might also be cases where not all “kirby file types” should be handled equally, like jpg vs. psd or code files .js vs .html - that would need filtering by extension - so maybe also a slightly more flexible solution - but your nice simplistic example, was also the first thing that came to my mind :thumbsup:


Doesn’t sound like anything Kirby’s core/panel will be able to do soon (my personal perception), especially when foxussing not on Kirby’s file types, but such fine detailed ones.

Does the Kirby builder plugin work as file field?

If so, you could have a blueprint like:

      label: Title
      type: text
      label: Filetypes
      type: builder
          label: jpg
          label: psd

And then in your template:

$filetype = $page->filetype()->toStructure(); 

if ($filetype->_fieldset() == 'jpg') {
} elseif (($filetype->_fieldset() == 'psd') {
} else {


Completely untested, just an idea I had.


I was in desperate need for something like this. I don’t know if there is a solution for this today in the core. At least I did not find anything.