# `area`

An area field allows editors to add, edit, and arrange a series of widgets. The properties configured in options specify the allowed widget types and the configuration for those widgets.

# Module field definition

// Configuring the `main` area field in a module's `fields.add` subsection:
main: {
  label: 'Main column',
  type: 'area',
  options: {
    widgets: {
      '@apostrophecms/rich-text': {}
    }
  }
}

# Settings

# Required

Property	Type	Default	Description
`label`	String	n/a	Sets the visible label for the field in the UI
`type`	String	n/a	Specifies the field type (`area` for this type)
`options`	Object	n/a	An object containing widget configuration. See below.

# Optional

Property	Type	Default	Description
`required`	Boolean	`false`	If true, the field is mandatory.
`help`	String	n/a	Help text for the content editor
`htmlHelp`	String	n/a	Help text with support for HTML markup
`if`	Object	`{}`	Conditions to meet before the field is active. See the guide for details.

# `options`

Area inputs have additional settings configured in an options object:

# `max`

Type: integer

The maximum number of widgets allowed in the area.

add: {
  main: {
    label: 'Main column',
    type: 'area',
    options: {
      max: 1, // 👈 Limits the area to a single image widget.
      widgets: {
        '@apostrophecms/image': {}
      }
    }
  }
}

# `widgets`

Type: object

Widgets names are added as keys to the widgets object, with their individual configurations (if needed) as the key value objects. Note: widget keys in area configuration are their associated module names minus the -widget suffix (e.g., 'callout-widget' is configured as simply 'callout'). Since all widget module names end with that suffix, it is not required for less repetition.

Configuring a widget type in an area field applies that configuration to the widget type only in this area's context. So a rich text widget with configured toolbar and styles in the area field would not automatically apply to a rich text widget in a different area field. (Though some widgets, including the core rich text widget, may support default configurations.)

add: {
  main: {
    label: 'Main column',
    type: 'area',
    options: {
      // Configuring four widget types as options in this area,
      // one of which has its own configuration when used in this
      // specific area. ⬇
      widgets: {
        '@apostrophecms/image': {},
        '@apostrophecms/rich-text': {
          toolbar: [ 'bold', 'italic' ]
        },
        '@apostrophecms/video': {},
        '@apostrophecms/html': {}
      }
    }
  }
}

# Use in templates

Use the area template tag with arguments for the context and the name of the area field in that context:

{% area context, area-name %}

The "context" may be a page, piece, widget, or array field item, as referenced in the template. All configuration from the field definition is applied automatically from the relevant schema configuration.

<!-- Inserting the `main` area field for a page. -->
<section>
  {% area data.page, 'main' %}
</section>
<!-- Inserting the `photo` area field for array items. -->
<div>
  {% for item in data.page.photos %}
    {% area item, 'photo' %}
  {% endfor %}
</div>

NOTE

For more information on how areas changed from Apostrophe 2, see the Coming from 2.x guide section on areas.

← Query builders array →

# area