Fieldsets are the tool used by your Control Panel to create publish forms. They establish your content model. Essentially, a schema that defines your fields, data types, and the interface used to manage them.

Learn by watching!
Check out the fundamentals screencast on Fieldsets.

What is a fieldset?

A fieldset is YAML file that defines a list of fields used to create content. They’re reusuable, highly configurable, and the cornerstone of a customized and tailor-fit Control Panel.

Your fieldsets are kept in the site/settings/fieldsets directory. The main section of a fieldset is the fields key which allows you to set and configure any number of fields utilizing any combination of the available fieldtypes.

An example of what a fieldset might look like:

title: Blog Post
  content:                # The template tag, i.e. {{ content }}
    display: Content      # The CP field label
    type: markdown        # The fieldtype
    instructions: Write!  # Instructional text
    validate: required    # Validation rules
    display: Author
    type: users
    default: current
    max_items: 1

Using a fieldset

To assign a fieldset to a piece of content, add a fieldset key to its YAML data.

Via content

You may add it directly to a page, entry, global set, or taxonomy term. This may be useful if you have a need for a single-use fieldset. For example, one page may require a specific fieldset.

Via container

You may also add it to the corresponding content containers (Collection, Taxonomy, Asset Container, etc) which will cascade down to all of its items. For example, adding fieldset to a Collection’s folder.yaml will ensure that all the entries (new and existing) will use that fieldset.

If you’ve defined a container level fieldset, you may still override it on the content level.

Configuring a fieldset

Naming fields

You can name your fields any way you choose, but each field name needs to be unique. You cannot use hyphens, but underscores are okay.

Required field settings

In the snippet above, the only thing that’s really required is the type key. Even without that, Statamic will treat it as a text fieldtype by default.

Some fieldtypes will have their own required settings. For example, the assets fieldtype requires that you specify a container.

Validation Rules

Each field can accept a pipe-delimited list of Laravel validation rules.

For example:

    type: text
    validate: required|alpha_dash|between:5,10

This would make the field required, ensure only alpha-numeric characters and dashes are used, and that the text is between 5 and 10 characters long.

Note that not every validation rule would be usable in Statamic. For instance, the database rules (exists, unique, etc) would not apply since we do not use a database.

Reusing fields across fieldsets

It’s fairly common to want to repeat certain fields across multiple fieldsets. In this case, you may use the Partial fieldtype to include another fieldset. Any of the partial fieldset’s fields will be included where you specify.

Conditional Fields

It’s possible to have top-level fields be displayed only under certain conditions. You may specify various rules under either the show_when or hide_when keys.

Important: Conditionals work on top-level fields only, not meta fields (fields that include other fields) like Replicator, Bard, and Grid.

A simple example might be to show a field when a toggle is set to “on”.

title: Blog Post
    type: toggle
    type: users
    max_items: 1
      has_author: true

If you don’t need to toggle it but instead “just show” the author field, you may be interested in the Revealer fieldtype.

Here’s another example using a select field:

title: Blog Post
    type: select
      - text
      - image
      - video
    type: text
      post_type: video
    type: assets
    container: main
    max_files: 1
      post_type: image
  • The youtube_id field will only be displayed when the post_type field has video selected.
  • The image field will only be displayed when the post_type value is image.

Not Nulls

You may specify a value to be “not null” which is handy when you need to say “Show this when another field has any value.”

  that_field: not null

Multiple fields

You can combine fields by adding to the show_when or hide_when array.

The following says: “Show when this_field is bacon AND that_field is cheeseburger

  this_field: bacon
  that_field: cheeseburger

You can use “OR” rules by prepending fields with or_.
The following says: “Show when this_field is bacon OR that_field is cheeseburger

  this_field: bacon
  or_that_field: cheeseburger

You may specify multiple values for a single field by using an array for the value.
The following says: “Show when this_field is one of bacon, eggs, or hash browns

  this_field: [bacon, eggs, hash brows]

Custom Logic

If you need something more complex than the YAML syntax provides, you may write your own logic.

In your site/helpers/cp/scripts.js file (or within an addon), you should add a function to the Statamic.conditions object.

Statamic.conditions.reallyLovesFood = function (fields) {
    return fields['favorite_foods'].length > 10;
    type: list
    type: textarea
    show_when: reallyLovesFood

This will present the user the ability to declare their obvious love for food in the food_haiku field if more than 10 favorite foods have been listed.

Last modified on March 13, 2018