Components, available as an experimental feature since Bricks 1.12, let you create reusable elements.
The content (text, icons, images, etc.) in each instance is customizable through properties. 😍
While templates serve as the blueprint for specific pages, components are the blueprints for specific elements that you want to reuse and even customize throughout your website.
Create a component from an element (including all its children) such as a card, navigation, or even a hero section, and reuse it anywhere else on your site.
Any change to the main component automatically applies to every instance of this component.
This keeps the structure and style of those reusable elements consistent throughout your website.
Resulting in an extremely consistent, scalable, and easy to maintain workflow. 🚀
How to create a component
Create a component from any element, except Template & Filter elements, by right-clicking on the element, and select the Save as component action.
In the popup that appears, enter a name (required), category (optional), and description (optional) for your new component. Once done, click Create to finish creating your component.
Once created, you can insert this new component anywhere on your site.
Components Library
You can access all components from the Components tab, located next to the Elements panel tab.
From here you can add a component to the canvas or structure panel via drag & drop or click (as you do with any other element).
You can also perform the following actions by clicking the respective icons in the Components tab:
- Import: Import a components JSON file from another installation.
- Export: Export all components of your site as a JSON file. To export a specific component, hover over it, and click the “export” action icon.
- Delete: Click the “delete” icon to enter the delete mode. Once activated, hover over the component you want to delete, and click the “delete” icon. We recommend to first export all components before performing any deletion.
Instances – How to reuse a component
Adding a component to a page, creates a so-called Instance of that component.
Every change to the main component automatically reflects in all instances of this component, not just on that particular page, but throughout your entire website.
The following screenshot show three instances of our Card component:
Before we explore customizing our instances, let’s have a look at …
Editing the main component
To view and edit the elements of the main component, which is the source for all its instances, right-click on any instance of the component and select Edit component.
Alternatively, you can also click the gear icon in the control panel header of the instance to enter the component editing mode:
You are now editing the main component. Indicated by the purple MAIN COMPONENT label in the control panel header.
As mentioned before, any change you perform on the main component applies to all instances of this component on your site.
The main component header contains the following actions:
- Instance (arrow icon): Exit the component edit mode, and brings you back to the instance of this component you were editing previously. Pressing the ESCAPE key also exists the main component.
- Description (info icon): Click to show/hide the component description (editable).
- Category (folder icon): Click to show/hide the component category (editable).
- Properties (box icon): Click to view the component properties panel.
Now that we are editing the main component you can view and edit all elements inside this component from the structure panel:
To edit the title of our Card component we simply select the Heading element inside our component, and change its text to “Just a card”.
All instances of our Card component automatically reflect this change:
While this is great for using the exact same element multiple times throughout your site, and updating the main component automatically applies every change to all instances, the real power of components lies in their ability to customize the content of each instance through Properties.
Properties
Properties allow you to expose content settings (such as text, links, icons, images, etc.) for each instance.
Lets create some properties so each Card instance on our website can have a unique title and image.
There’s a simple, two-step process of (1) creating and (2) connecting properties.
NOTE: Creating and managing properties requires full builder access.
1) Creating a property
To access the properties panel, click on any instance of the component you want to edit.
Then click the “CREATE” button in the properties control panel on the left-hand side:
If there are instances of the component you want to edit on the current page, visit the Components library, hover over the respective component, and click the edit icon.
If you are editing the main component, you can access the Properties panel by clicking the box icon in the panel header (highlighted in the screenshot below).
Property types
Select the type of property you want to create.
We want to expose the heading of our card component, so we select the property type Text.
Next, set a name, description, and default value for your property, then click the “CREATE” button to create your property.
The property name is mandatory. Choose a descriptive name. This is especially important for complex components with potentially dozens of different properties, so everyone working with this component knows exactly what each property is for.
Providing a short property description is optional, but can be helpful for anyone working with component.
The default value is optional. It’ll be used for the setting you connect this property to.
2) Connecting a property to a setting
Now that we’ve created our first property, we need to connect it with our desired element setting(s).
The properties panel shows a message if any unconnected properties are detected. Unconnected properties also have a “broken link” icon next to their name.
Lets connect our “Card heading” text property to the “Heading” element of our card component. So we select the “Heading” element inside our component.
You’ll notice the purple + icon next to the text control of our Heading element.
This + icon indicates that our component has properties that we can connect with this specific setting.
Clicking on this + icon reveals a list of properties that we can connect to this setting.
We only created one text property, but if your component has multiple text properties then you’ll see all of them in the property dropdown.
We select the “Card heading” property. Once selected, the text setting in the control panel displays the name of the property we just connected this property with.
Our default property value “Default Card heading” that we set when we created this property in the previous step is now used as the text value for our all our Card headings.
And that’s it. You successfully created and connected your first property. 🥳
You can continue creating and connecting as many properties as needed.
We used the same two-step process of creating & connecting for our image property so we can customize the “Card image” as well. Our component now looks like this:
Disconnecting a property
To disconnect a property from a settings, click the connected property setting, hover over the connected property name, and click the “unlink” icon.
Customizing an instance
Right now, all our Card components, display the exact same content. But we’ve created two properties so we can customize the title & image of each Card instance. So lets do that by selecting the Card instance that you want to customize, then set custom property values in the control panel like this:
We could continue to also expose the button text through a text property, but you get the picture.
Components as loops and inside loops
Components are also compatible with query loop. Either by enabling the loop on the component root or by having a loop inside the component.
In the following screenshot we use our Card component inside a loop. The Card title uses the post_title dynamic data tag and the Card image uses the featured_image tag to render the post title & featured image of the loop results.
Unlinking a component
To unlink an instance from a component, simply right-click on the instance, and select “Unlink component”. This instance is no longer tied to your main component, and can be edited independently, like any other normal element.
PLANNED: Global element to component converter
We plan on providing a “Global element to Component” converter, that lets you convert all your global elements to components with one click. Once implemented we’ll deprecate global elements in Bricks, which are redundant now that we’ve got components, plus they never really took off in Bricks and are much better implementable through components anyway.
Notes & Tips
- A component must have exactly one root element
- Components within components are not supported
- Components can’t be created from Template and Query Filter elements
- Components are easy to spot in the builder by their purple color
- You can change the label of each instance like any other element