Builder widgets streamline the development process so you can focus on creating engaging user interfaces.
With these widgets, you can create interactive elements such as collapsible sections, image sliders, and tabbed content, enhancing the appeal and functionality of your content.
If you're using the Gen 1 React SDK, you must install widgets separately. For Gen 2 SDKs: Most widgets are built-in, except for the Carousel which is currently a work in progress.
For more detail on the Builder SDKs, read SDK Comparison.
To get the most out of this document, you should already have the following:
- An app already Integrated with Builder
In your project, install the Builder Widgets package by running the following npm install in the terminal:
npm install @builder.io/widgetsIn your React application, import the Builder Widgets package to register the widgets:
import '@builder.io/widgets';Include this import statement wherever you render a <BuilderComponent /> in your code. This registers the widgets and makes them available for use in the Visual Editor, as well as ensures proper rendering during both client-side and server-side rendering.
If you're already using widgets, you can keep them up-to-date with:
npm install @builder.io/widgets@latestOr, if you're using yarn:
yarn add @builder.io/widgets@latestTo improve performance, you can lazy load the Builder widgets package by asynchronously importing only the widgets used in Builder content. This means that widgets only load when needed, which helps you streamline user experience (UX) and more efficiently use resources.
Instead of importing the root package synchronously, use the following import statement in Next.js:
import '@builder.io/widgets/dist/lib/builder-widgets-async';This enables lazy loading of the widgets, which ensures they are loaded only as needed.
For other frameworks, explicitly lazy load the widget components by registering them with your chosen lazy loading library.
The following example uses Loadable, the React code-splitting library:
import { Builder } from '@builder.io/react';
import { accordionConfig } from '@builder.io/widgets/dist/lib/components/Accordion.config';
import loadable from '@loadable/component';
Builder.registerComponent(
loadable(() =>
import('@builder.io/widgets/dist/lib/components/Accordion').then(mod => mod.AccordionComponent)
),
accordionConfig
);In this example, the Accordion component from the Builder Widgets package is registered using Loadable's lazy loading functionality. The component is loaded only when it's used in your content.
If your framework supports React.lazy, you can use this technique in a similar manner as Loadable to lazy load the Builder Widgets components when needed.
After installing widgets, find them in the Layouts section of the Insert tab.
Tip: The Layouts section only displays if you've installed and imported the Widgets package or are using the Fallback Editor or fiddle.
The Accordion component renders an accordion-style UI. It accepts an array of items, each consisting of a title and a detail section. Users can click on the title to expand and collapse the corresponding detail section.
The component supports options such as displaying as a grid, allowing only one item to be open at a time, and customizing the layout.
To use the Accordion:
- Install the Widgets package.
- Go to the Insert tab > Layouts.
- Drag in the Accordion widget.
- Click Edit to adjust settings.
The following video shows dragging in an Accordion widget, editing some of the settings in the Accordion's Edit dialogue. Just as with other blocks, you can apply styles to get the look and feel you want in your Accordion.
Note that these instructions are for the Gen 1 SDK. For the Gen 2 SDKs, the Carousel is currently a work in progress.
The Carousel component renders interactive carousels or sliders using the react-slick library. It accepts an array of slides and supports options like autoplay, navigation buttons, responsive settings, and customization of slide content and styles.
This component can render static content as well as dynamic content. With its customizable settings and seamless integration, the Carousel component provides an intuitive way to showcase and navigate through a collection of content.
To use the Carousel:
- Install the Widgets package.
- Go to the Insert tab > Layouts.
- Drag in the Carousel widget.
- Click Edit to adjust settings.
The following video shows dragging a Carousel widget, editing some of the settings in the Carousel's Edit dialogue, and clicking through the slides. Just as with other blocks, you can apply styles to get the look and feel you want in your Carousel.
Masonry: dynamic grid layouts
The Masonry Component implements a Masonry layout using the react-masonry-component library. It takes an array of tiles, which can be React nodes or Builder.io blocks, and supports options for column width, gutter size, and responsive layout.
This widget automatically adjusts the size and position of items based on the available space, resulting in visually appealing grid layouts. Masonry components support dynamic loading, responsive design, and customizable styles.
Tabs provide a convenient way to organize and present multiple sections of content within a limited space. It accepts an array of tabs, each consisting of a label and corresponding content. Users can switch between tabs by clicking on the labels, and the active tab's content is displayed.
To use the Tabs component:
- Install the Widgets package.
- Go to the Insert tab > Layouts.
- Drag in the Tabs widget.
- Click Edit to adjust settings.
The component offers additional features like setting a default active tab, collapsible tabs to toggle their visibility, customizable tab header layout options, and the ability to style the active tab to distinguish it from others.
The following video shows dragging in the Tabs widget and editing its settings:
For more detail on the available widgets, check out the code on GitHub.
