Reusable elements in Bubble are self-contained groups of elements, workflows, and custom states that you build once and insert across multiple pages. They maintain visual and functional consistency — update the reusable element once and every instance updates. You pass data in through element properties and data sources, and communicate out through custom states and custom events. This tutorial covers creating, configuring, and organizing a reusable component library.
Overview: Reusable Elements in Bubble
This tutorial shows you how to build and manage reusable elements for consistent, maintainable Bubble apps. You will learn to create components, pass data between pages and components, and organize a scalable element library.
Prerequisites
- A Bubble app with multiple pages that share common UI patterns
- Understanding of Groups, custom states, and workflows
- Elements that you want to reuse (headers, footers, sidebars, cards)
Step-by-step guide
Create your first reusable element
Create your first reusable element
In the Design tab, click the page dropdown (top-left) and select 'New reusable element'. Name it descriptively — 'header_nav', 'sidebar_menu', 'user_card'. Choose the element type (Group, Popup, or Floating Group). Build the component inside this reusable element just like you would on a page. Add elements, styles, conditionals, and workflows. Everything inside is self-contained.
Pro tip: Name reusable elements with a prefix like 're_' or 'comp_' so they are easy to identify in the element picker.
Expected result: A reusable element is created with its own design canvas, ready to be built as a self-contained component.
Insert the reusable element on pages
Insert the reusable element on pages
On any page, click the '+' icon and search for your reusable element name. Drag it onto the page. You can resize and position it like any other element. Each page can have multiple instances of the same reusable element. Changes to the reusable element's definition automatically update every instance across all pages.
Expected result: The reusable element appears on the page and displays its content, consistent with every other instance.
Pass data into the reusable element
Pass data into the reusable element
There are several ways to send data into a reusable element. Method 1 — Set the element's data source: select the reusable element on the page, then set its 'Data source' property (works if the reusable has a content type). Method 2 — Custom properties (recommended): on the reusable element's definition, add custom properties with types and default values. On each page instance, set these properties individually. Inside the reusable element, reference properties with 'This Reusable Element's [property name]'.
Expected result: Data flows from the parent page into the reusable element through data source or custom properties.
Communicate from reusable element to parent page
Communicate from reusable element to parent page
Reusable elements cannot directly trigger parent page workflows. Instead, use custom states: add a custom state to the reusable element that the parent page reads. For example, a reusable search bar sets a 'search_text' state, and the parent page uses it as a filter. The parent can watch this state with a 'Do when condition is true' event. Alternatively, use URL parameters for cross-component communication.
Expected result: The parent page can react to changes in the reusable element's custom states.
Organize a component library
Organize a component library
Create a set of standard reusable elements for your app: header, footer, sidebar, user avatar, notification badge, card layouts, form sections, and empty states. Use consistent naming: 're_header', 're_footer', 're_card_product'. Keep a design reference page (unlisted) where you place one instance of each component for visual reference. Document each component's properties and expected data in the element's notes.
Expected result: A well-organized library of reusable components with clear naming and documentation.
Handle responsive behavior in reusable elements
Handle responsive behavior in reusable elements
Reusable elements must be responsive on their own since they can be placed in different contexts. Use the responsive engine (Row, Column, Align to Parent) inside the reusable element with percentage-based widths. Test the reusable element at different sizes by resizing it on various pages. If the reusable element was built with the legacy responsive engine, it must be upgraded separately — page upgrades do not cascade to reusable elements.
Expected result: Reusable elements adapt to their container size and display correctly across different page contexts and breakpoints.
Complete working example
1REUSABLE ELEMENTS — SUMMARY2==============================34CREATING:5 Page dropdown → New reusable element6 Name: re_header, re_sidebar, re_card_product7 Type: Group, Popup, or Floating Group89INSERTING:10 Click '+' → search reusable name → drag to page11 Resize and position as needed12 Changes to definition update all instances1314DATA IN (parent → reusable):15 Method 1: Data source on the element instance16 Method 2: Custom properties (recommended)17 Define in reusable: property name + type18 Set per instance on each page19 Reference: This Reusable Element's [property]2021DATA OUT (reusable → parent):22 Custom states on the reusable element23 Parent reads: ReusableElement's [state]24 Parent watches: Do when condition is true2526LIBRARY ORGANIZATION:27 Naming: re_header, re_footer, re_card_*28 Reference page: one instance of each29 Documentation: notes on each component3031RESPONSIVE:32 Use % widths inside reusable elements33 Test at multiple container sizes34 Upgrade legacy responsive separatelyCommon mistakes when creating Reusable Elements in Bubble
Why it's a problem: Trying to trigger a parent page workflow from inside a reusable element
How to avoid: Use custom states on the reusable element that the parent page watches with 'Do when condition is true' events
Why it's a problem: Not using custom properties for data passing
How to avoid: Define custom properties on the reusable element for each piece of data it needs from the parent
Why it's a problem: Editing a reusable element without realizing it affects all instances
How to avoid: Be intentional when editing reusable elements. If you need a variation, create a new reusable element rather than adding complex conditionals
Best practices
- Use custom properties (not just data source) for flexible data passing
- Name reusable elements with a consistent prefix for easy discovery
- Keep reusable elements focused on one purpose — header, card, form section
- Use custom states for reusable-to-parent communication
- Build responsive reusable elements with percentage widths
- Maintain a reference page showing all components for visual documentation
- Avoid deeply nested reusable elements (reusables inside reusables) as they complicate debugging
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I want to create reusable components in Bubble.io for my app's header, sidebar, and product cards. How do I build them, pass data in and out, and organize them as a component library?
Create reusable elements for my app: a header with navigation and user avatar, a sidebar with menu items, and a product card that accepts product data via properties. Show me how to pass data in and communicate back to the parent page.
Frequently asked questions
Can I nest reusable elements inside other reusable elements?
Yes, but use this sparingly. Deeply nested reusable elements are harder to debug and can cause performance issues. One level of nesting is usually sufficient.
What happens if I delete a reusable element?
Pages that use the deleted reusable element will show a 'Deleted reusable element' placeholder. The page will not break, but the component will be missing.
Can I convert an existing group into a reusable element?
Yes. Right-click the group on a page and select 'Convert to a reusable element'. Bubble moves it into its own definition and replaces the original with an instance.
Do reusable elements share custom states across instances?
No. Each instance of a reusable element has its own independent custom states. Setting a state on one instance does not affect others.
Can RapidDev help build a component library for my Bubble app?
Yes. RapidDev can design and build a comprehensive component library with consistent styling, data flow patterns, and documentation for your Bubble app.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation