Skip to main content


In crafting large-scale websites, particularly in collaborative team settings, a standardized approach to field naming is crucial. Our conventions have been battle-tested in real-world projects, ensuring seamless developer collaboration and consistent code quality. These guidelines are designed to improve project clarity and maintainability, making them an essential practice for any development team looking to scale their Craft CMS projects effectively.

Field Groups in the Sidebar

We recommend to organize your fields into groups in the sidebar by using the names of your sections. Here are some examples:
structureTeam, structurePartners, channelNews, etc.

If fields are shared across multiple sections, create a group in the sidebar named shared. For global fields, create a group named global.

Fields in a section with only one entry type

Prefix the fields with the name of the section. For example, for a channel channelEvents with only one entry type:

Name Handle
Location channelEventsLocation
Starting Date

Fields in a section with multiple entry types

If your section has multiple entry types, include the entry type in the handle. For example, for a section structurePages with multiple entry types:

In the sidebar, only one field group will be present and named structurePages.

Name Handle
Introduction structurePagesAboutIntroduction
Call to action text structurePagesTeamCtaText
Values structurePagesAboutValues
Why prefix with the section?

Imagine a large site with a Events structure as well as an Events single page. Both sections have an Intro field, but they are different. Prefixing solves this issue effectively. In this case, we would have singleEventsIntro and structureEventsIntro.

Matrix Fields

The matrix field will take the handle as seen previously. For a main matrix shared across multiple sections, it could be named sharedMainMatrix.

Blocks within Matrix Fields

Blocks within a matrix are scoped to that matrix. Use only the prefix block.

  • blockTextImg, blockGallery, etc.

Fields within Blocks

For the fields within your blocks, use the name of the block as a prefix. For example:

  • blockGalleryIntro, blockGalleryAssets, blockGalleryLink, etc.

This structured approach to naming fields helps in creating a consistent and manageable schema, especially beneficial as the complexity of the site grows. It allows developers to quickly identify the purpose and location of a field within the project.