Component

Discover the building blocks that shape your content.

In the world of headless CMS, components are the basic elements that define the shape of your content. They provide the structure and flexibility needed to create a wide variety of content types, making it easier to manage and ensure consistency across channels.

For example, a hero section component may contain a headline, an image, and a call-to-action button — which may be another component. By breaking the section into smaller pieces, you can change each element independently, allowing you to make quick changes that are reflected everywhere it is used.

You can mix and match components to define different content shapes — just as Lego pieces that you can combine in numerous ways to build unique structures.

Types

When creating a component, you can choose from two types of components, depending on the level of flexibility you need:

Regular component
Simple elements with a fixed structure and a fixed set of attributes.
Union component
Elements with variations, combining multiple regular components into one.

Let's see some examples to illustrate when you should use one component type over the other.

Suppose you want to display a banner in the middle of your blog posts. In that case, a regular component is the way to go, as it always uses the same attributes and does not need extra flexibility:

Now, suppose you need flexibility to accommodate different types of content. In that case, you should consider a union component like the one below:

In the above example, we have combined three regular components – a text banner, an image banner, and a form banner – into a single union component. This way, you can choose the variation that works best for a given post or experience.

Schema

Once you have determined the type of component you need, the next step is to define its structure, or schema.

For regular components, it is a matter of defining the attributes that make up its structure. For union components, this means selecting the components you want to use as choices.

You can define a schema using the visual interface or upload a JSON file containing the definition. The interface allows you to easily configure attributes in a few clicks, while the JSON file is perfect for those who prefer to work with code.

Check out the Schema reference for more information on defining a component schema.

Attributes

Attributes are like placeholders in a template. They allow you to easily enter different types of information while maintaining a consistent structure across content.

There are five primary attribute types to choose from:

Text
Textual values like titles, descriptions, and paragraphs.
Boolean
True or false values — ideal for yes/no or on/off options.
Number
Numeric values such as prices, quantities, and percentages.
List
Collections of items such as lists of tags, images, or products. The items can be of any attribute type, including nested lists or structures.
Structure
A group of related attributes, such as a product description with a title, description, price, and image.

Besides the primary attribute types listed above, there are also specialized types for specific purposes:

Component
A reference to another component.
Enumeration
A predefined list of options or choices.
URL
A URL to a web page or resource.
File
A URL to an uploaded file, such as an image, video, or document.
Color
A hexadecimal color representation.

Attributes can also include validation rules and user interface customization options. For example, you can specify if they are required or optional, set a maximum length for a text, or a minimum value for a number. You can even control the order in which they appear in the content editor for a more intuitive editing experience.

See the Schema reference for more information on configuring attributes.

Versioning

As your application evolves, you may need to change your components. For example, you may want to add an attribute or change an existing one.

Making changes to a component can potentially break your application if done incorrectly. For example, removing a required attribute that is still needed on your front end may cause your application to crash.

To avoid this problem, we have built a versioning system that allows you to seamlessly update your components without breaking your application.

This is a high-level overview of how it works:

You modify the component schema to make the desired changes.
We create a new version with the updated schema and keep the old version untouched.
While you adjust the content of affected slots or experiences, we continue to serve the old version to your application.

To assist you with step 3, we indicate the exact slots that require your review whenever you make a breaking change:

To learn more about how to update your slots, refer to the Versioning section in the slot documentation.

Complexity

When designing a component, it is important to keep in mind that the more complex a component is, the more difficult it is to create and update content.

The complexity score tells how complex a component is based on its structure and attributes. The higher the score, the more complex the component.

To calculate the score, start with 0 and then add up the complexity of the component's attributes as follows:

Structures: Count 1 for the structure itself, and add the complexity of its attributes.
Lists: Count 1 for the list itself, and add the complexity of its item type.
Primitives: Count 1 for each primitive type (text, boolean, and number).
Unions: Add the complexity of the most complex component in the union.
References: Add the complexity of the referenced component.

Now let's apply this to an example. Suppose we have a product listing component that contains a list of products. Each product has a title, an image, and a price. The complexity of the component would be calculated as follows:

Count 1 for the list
Count 1 for the product structure
Count 1 for each of the product attributes (title, image, and price).

That gives us a complexity score of 5.

Limits

We enforce some limits on content schemas to ensure that components remain performant and manageable as your content model evolves.

These are the limits that apply to components:

Up to 30 attributes per structure
Up to 5 component references
Nesting up to 5 levels deep
Maximum of 10 components in a union
Maximum complexity score of 50.

For tips on designing components that are both flexible and maintainable, check out the Component Design guide.