Skip to content

[WIP] components doc changes to include elements and components #126

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
basslikethefish wants to merge 8 commits into
base: main
Choose a base branch
from
Open

[WIP] components doc changes to include elements and components #126

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
7ba38e3
components doc changes to include elements and components
basslikethefish Jul 9, 2025
1cfacf2
Update product/components.mdx
basslikethefish Jul 9, 2025
46895c0
Update product/components.mdx
basslikethefish Jul 9, 2025
6beb4ae
Update product/components.mdx
basslikethefish Jul 9, 2025
c4f42de
Update product/components.mdx
basslikethefish Jul 9, 2025
8b54b8f
Update product/components.mdx
basslikethefish Jul 9, 2025
9b235b6
Update product/components.mdx
basslikethefish Jul 9, 2025
4d2d44c
Address review james's comments and accept suggestions
basslikethefish Jul 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion developer/guides/components/accordion.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ description: "Learn how to create a built-in accordion component that integrates

This tutorial walks you through how to build an accordion component in Makeswift. Instead of building an accordion from scratch, we’ll leverage the [Radix UI react accordion component](https://www.radix-ui.com/primitives/docs/components/accordion). Then, we’ll register it with Makeswift and use Makeswift controls to enable it to be visually editable.

At the end, you'll get a feel for how to build [built-in components](/developer/guides/components/built-in-components) for Makeswift and make them editable using controls.
At the end, you'll get a feel for how to build [built-in components](/product/components#built-in-components) for Makeswift and make them editable using controls.

Here’s a sneak peak of the final component:

Expand Down
163 changes: 121 additions & 42 deletions product/components.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,39 @@
---
title: "Components"
description: "Makeswift leverages the power of React to give you unparalleled flexibility and control over your website's design and functionality on an ongoing basis."
title: "Components and Elements"
icon: "cube" iconType: "solid"
---

Makeswift leverages the power of React to give you unparalleled flexibility and control over your website's design and functionality on an ongoing basis.
Copy link
Collaborator

@jamesqquick jamesqquick Jul 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it make sense to not mention react to start since for visually created components, code doesn't factor in?

Copy link
Collaborator Author

@basslikethefish basslikethefish Jul 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't disagree, but this is from the current Product Components documentation haha.


**Components** are the building blocks of your website that show up in your Component Toolbar. Once you drag and drop a component onto your page, it becomes an **Element** and is visible on both your Canvas and [Elements Panel](/product/builder-basics#elements-panel).

Elements on your page can be styled and manipulated based on the [controls](/developer/reference/controls) that are made available to you via the Component's properties.

# Components

There are two types of components that show up in your Component Toolbar:

<Columns cols={2}>
<Card title="Built-in Components" icon="code">
Code components that are registered with your Makeswift.
</Card>
<Card title="Global Components" icon="cube">
Visually created components that are created in Makeswift.
</Card>
</Columns>

## Built-in components

There are four components that come standard with the Makeswift default host:
Built-in components are standard React components that are registered with your host. You can use any react component as your starting point for a new component, and follow the [registration documentation](/developer/guides/components/card#registering-the-component) to make it available in your component toolbar.

<Tip>
Checkout [VIBES](https://vibes.site/docs/soul/introduction) for an example of
a react component library that you can use to start!
</Tip>

The controls that are available to you are configured in code but can be expanded or contracted upon by a developer.

In addition to registering your own components with Makeswift, there are a few built-in components that are available to you by default.

<AccordionGroup>
<Accordion title="Box">
Expand Down Expand Up @@ -77,54 +104,18 @@ You can select from a list of premade styles for your buttons. Along with styles
</Accordion>
</AccordionGroup>

## Naming components

You can name a component by selecting it and changing the default name at the top of the [Properties Sidebar](/product/builder-basics). Component names must be alphanumeric and cannot contain any spaces.

<Frame>
![Custom component name input](/images/builder/components-custom-name.jpeg)
</Frame>

Component names are displayed in [Breadcrumbs](/product/layouts#selecting-components) and the [Elements Panel](/product/builder-basics#elements-panel) making it easier to discern between different components.

<Frame>
![Component label showed in
breadcrumbs](/images/builder/components-breadcrumb-label.jpeg)
</Frame>

Custom component names also serve as the `id` property added to the component's HTML. This allows them to be scrolled to with buttons, images, and text links. All components with custom names will appear in the **Scroll to element** dropdown found in the **on click** panel.

<Frame>
![components in dropdown click
panel](/images/builder/components-scroll-to-custom-name.jpeg)
</Frame>

## Component actions

Actions for selected components can be found at the top right of the [Properties Sidebar](/product/builder-basics) or by using keyboard shortcuts.

<Frame>
![Menu actions for component](/images/builder/components-menu-actions.jpeg)
</Frame>

- Duplicate a component `⌘ + D` - creates an exact copy, including nested components, either below or next to the original
- Copy a component `⌘ + C` - copies the selected component to your clipboard
- Paste a component `⌘ + V` - places the copied component in the [Canvas](/product/builder-basics) (you choose exactly where to place it)
- Delete a component `DELETE` - deletes the selected component

## Global Components

Global Components are groups of components that can be saved and reused across your entire site. If you make an update to a Global Component, every instance of that component on your site will be updated as well.
Global components are components that you create and save visually within Makeswift and can be used across your entire site. They can be comprised of Built-in components, elements, and even other global components. They provide an easy way for you to create a reusable layout that you can easily drag an drop onto your canvas, without engaging with a developer.

### Creating a Global Component

To create a Global Component, select the Box containing the components you want to turn into a Global Component. Then, click on the cube icon found at the top of the [Properties Sidebar](/product/builder-basics).
You can create a global component by selecting an Element or group of Elements on your page and clicking the cube icon at the top of the [Properties Sidebar](/product/builder-basics). If you make an update to a Global Component, every instance of that component on your site will be updated as well.

<Frame>
![Create global
component](/images/builder/components-creat-global-component.jpeg)
</Frame>

Name your global component and click **Yes, continue**.

You can find your newly created Global Components in the Component Toolbar by clicking the plus icon. Then, you can click and drag to place it on the page.
Expand Down Expand Up @@ -155,7 +146,6 @@ When you are done with edits, click the **Save** button at the top right of the
more about [publishing Global
Components](/product/publishing#publishing-site-resources).
</Note>

### Detaching from a Global Component

Changes to a Global Component are propogated to all instances across your site. If you'd like to use a Global Component as a starting point and don't want to keep it in sync with the original component, you can detach an individual instance.
Expand All @@ -174,3 +164,92 @@ As your list of components grow, you may want to organize them. You can do this
![Organizing components using
slash](/images/builder/components-organizing-with-slash.jpeg)
</Frame>

# Elements

Elements are instances of components on your canvas. While the difference can be subtle, what makes something an element is its unique placement and the specific customization data applied to it—essentially, an element is a component that’s been added and configured in a particular context.

<Tip>
For example, the *component* defines what properties can be changed like the
title on a card. But the *element* holds the actual value you set for that
property. So if you update the title in one card on your page, that change
belongs to that card element, not to the card component as a whole.
</Tip>

There are two types of elements that you may encounter on a page:
Copy link
Collaborator

@jamesqquick jamesqquick Jul 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Calling out two types of elements feels a bit weird to me. I think of it more hierarchical. Elements are instances of components on the canvas, and a built-in element is a specific type of element that is added to the canvas from code and can't be deleted visually.

Copy link
Collaborator Author

@basslikethefish basslikethefish Jul 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah definitely feel that. I can do a separate PR for the option to separate Components and Elements to make this work better. I struggled with this as I was trying to follow a pattern in explaining Built-in Components and elements, vs Visual/global components and standard elements.


<Columns cols={2}>
<Card title="Elements" icon="laptop-medical" style="solid">
Standard elements that are instances of components dragged onto the canvas.
</Card>
<Card title="Built-in Elements" icon="laptop-code">
Elements on the canvas that can be edited but cannot be moved or deleted
visually
</Card>
</Columns>

## Elements

Elements are instances of components that you can place on a page. This is the more common interaction between your component toolbar and canvas and is the entity that hosts the actual values you set to your components properties. They are the starting point for all Global Components. Elements can be moved, copied, pasted, named, and deleted.

### Naming elements

You can name an Element by selecting it and changing the default name at the top of the [Properties Sidebar](/product/builder-basics). Element names must be alphanumeric and cannot contain any spaces.

<Frame>
![Custom element name input](/images/builder/components-custom-name.jpeg)
</Frame>

Element names are displayed in [Breadcrumbs](/product/layouts#selecting-components) and the [Elements Panel](/product/builder-basics#elements-panel) making it easier to discern between different elements.

<Frame>
![Element label showed in
breadcrumbs](/images/builder/components-breadcrumb-label.jpeg)
</Frame>

Custom element names also serve as the `id` property added to the element's HTML. This allows them to be scrolled to with buttons, images, and text links. All elements with custom names will appear in the **Scroll to element** dropdown found in the **on click** panel.

<Frame>
![elements in dropdown click
panel](/images/builder/components-scroll-to-custom-name.jpeg)
</Frame>

### Element actions

Actions for selected elements can be found at the top right of the [Properties Sidebar](/product/builder-basics) or by using keyboard shortcuts.

<Frame>
![Menu actions for element](/images/builder/components-menu-actions.jpeg)
</Frame>

- Duplicate an element `⌘ + D` - creates an exact copy, including nested elements, either below or next to the original
- Copy an element `⌘ + C` - copies the selected element to your clipboard
- Paste an element `⌘ + V` - places the copied element in the [Canvas](/product/builder-basics) (you choose exactly where to place it)
- Delete an element `DELETE` - deletes the selected element

## Built-in Elements

<Warning>Placement and configuration of Built-in Elements are developer actions. For details see [`<MakeswiftComponent>`](/developer/reference/components/makeswift-component)</Warning>

These are instances of elements that are placed on the page in code and cannot be moved or deleted visually. What makes these elements and not components is that you can still change the property values within Makeswift, however the behavior is slightly different depending on the configuration.

Some Built-in Elements may propogate changes throughout your whole site, while others may be utilized to lock down what is editable on a specific page or page type. They are affectively components that are purpose built to live on a specific page and allow specific editing capabilities.

### Examples

Here are some common examples of where a Built-in Element may be preferred.

#### Navigation Bar

Implementing a Built-in Element for a Navigation bar allows for all new pages to automatically include a Navigation bar, without having to add it manually. Furthermore, any edits to the Navigation will propagate to all new and existing pages.

<Frame>
<img
src="/images/developer/reference/makeswift-component/header-finished.jpg"
alt="Header component showing on a page in the Makeswift Visual Builder"
/>
</Frame>

#### Blogs

Copy link
Collaborator

@jamesqquick jamesqquick Jul 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this a WIP?

Copy link
Collaborator Author

@basslikethefish basslikethefish Jul 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes sir

Copy link
Collaborator Author

@basslikethefish basslikethefish Jul 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

to clarify, I don't know how to create Built-in elements so I need help with a similar image to the built-in element nav bar here. Maybe you can help me with that?

Utilizing a Built-in Element for Blog content allows for editors to focus just on the copy for a blog, while