Skip to main content

​
Arguments

  1. ​
    component
    Component
    required
    Your component to be registered. This can be a React component or a function.
  2. ​
    options
    object
    required

    Options for site version and locale.

​
Examples

​
Registering a box

This example shows how to register a Box component. 'box' is the value for type, which must be unique, as Makeswift uses this value to identify the component. This value shouldn’t change once you use the component in the Makeswift builder. 'Box' is the label, which appears in the Makeswift builder. The example applies a Style control to the className prop.
makeswift/components.tsx
import { Style } from "@makeswift/runtime/controls";

import { runtime } from "./runtime";

function Box({ className }) {
  return <div className={className}>I'm a box!</div>;
}

runtime.registerComponent(Box, {
  type: "box",
  label: "Box",
  props: {
    className: Style({ properties: Style.All }),
  },
});

​
Creating sections

This example shows how to register a Cube and a Sphere component under a “Visuals” section. In each components’ label, use slashes to separate the section name and component name. In the Makeswift builder, both components appear under the same Visuals collapsible section:
Screenshot of registered component sections
makeswift/components.tsx
import { Style } from "@makeswift/runtime/controls";

function Cube({ className }) {
  return <div className={className}>Cube!</div>;
}

function Sphere({ className }) {
  return <div className={className}>Sphere!</div>;
}

runtime.registerComponent(Cube, {
  type: "cube",
  label: "Visuals/Cube",
  props: {
    className: Style({ properties: Style.All }),
  },
});

runtime.registerComponent(Sphere, {
  type: "sphere",
  label: "Visuals/Sphere",
  props: {
    className: Style({ properties: Style.All }),
  },
});

​
Overriding the built-in Suspense boundary

By default, the Makeswift runtime wraps registered components in a built-in <Suspense> boundary to transparently enable efficient server-side streaming and asynchronous data fetching. If your component already includes its own <Suspense> boundary, you can disable the built-in one by setting the builtinSuspense option to false: 
import { TextInput } from "@makeswift/runtime/controls";
import { runtime } from "./runtime";

function Discography({ artistId }: { artistId?: string }) {
  return (
    <>
      <h2>Discography</h2>
      {/* component's own Suspense boundary with a fallback */}
      <Suspense fallback={<div>Loading...</div>}>
        <AlbumList artistId={artistId} />
      </Suspense>
    </>
  );
}

runtime.registerComponent(Discography, {
  type: 'section-discography',
  label: 'Discography',
  builtinSuspense: false, // disable the built-in Suspense boundary
  props: {
    artistId: TextInput({ label: 'Artist ID' }),
  },
});

​
Adding custom icons

This example shows how to register an ImageGallery component with a custom icon. We import ComponentIcon from @makeswift/runtime and pass ComponentIcon.Gallery as the icon for our component.
You can find all available icons in the icons list section.
In the builder component tray, we can see our component with the selected icon.
Screenshot of registered component icons
makeswift/components.tsx
import { Style } from "@makeswift/runtime/controls";
import { ComponentIcon } from "@makeswift/runtime";

import { runtime } from "./runtime";

function ImageGallery({ className }) {
  return <div className={className}>I'm an image gallery!</div>;
}

runtime.registerComponent(Cube, {
  type: "image-galley",
  label: "ImageGallery",
  icon: ComponentIcon.Gallery,
  props: {
    className: Style({ properties: Style.All }),
  },
});

​
Adding a description

This example shows how to add a Circle component with a rich description. We can define a description string using markdown formatting, and pass it into the component description field. 
const mdDescription = `
# This is a larger heading

This is some text at the top of here

[![robot](https://plus.unsplash.com/premium_photo-1738614647383-0435fcb26a55?w=500&auto=format&fit=crop&q=60&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxleHBsb3JlLWZlZWR8NHx8fGVufDB8fHx8fA%3D%3D)](https://www.youtube.com/watch?v=dQw4w9WgXcQ)

## This is a smaller heading

This is a **description** about this component, click to [learn more](https://www.youtube.com/watch?v=dQw4w9WgXcQ).
* First Item
* Second item

This is a line with some \`\`<code/>\`\`
`
makeswift/components.tsx
import { Style } from "@makeswift/runtime/controls";

import { runtime } from "@/makeswift/runtime";

function Circle({ className }) {
  return <div className={className}>I'm a circle!</div>;
}

runtime.registerComponent(Circle, {
  type: "circle-tester",
  label: "Custom / Circle",
  icon: "chats",
  hidden: false,
  description: mdDescription,
  props: {
    className: Style({ properties: Style.All }),
  },
});
In the Properties Sidebar, we can see an info icon next to the component label. Hover over the label to open the description tooltip.
custom component description open
Descriptions that are longer than the standard tooltip will have a scrollbar to view the overflowing content.

​
Organizing registration code

As you register more components in makeswift/components.tsx, you may notice this file growing rather large. To keep your codebase organized, we recommend breaking out your Makeswift registration code into separate files and co-locating it with your component file. For example, if you have a Box component, you can create a Box.makeswift.ts file next to your Box.tsx file. This file will contain the registration code for the Box component.
Makeswift does not rely on this naming convention. Feel free to use whatever naming convention you prefer.
interface Props {
  className?: string;
}

function Box({ className }) {
  return <div className={className}>I'm a box!</div>;
}
Then update your makeswift/components.tsx file to import all of the component registrations, like so:
makeswift/components.ts
import "@/components/Box/Box.makeswift";
import "@/components/Cube/Cube.makeswift";
import "@/components/Sphere/Sphere.makeswift";
import "@/components/Circle/Circle.makeswift";
/*
 * Add all of your component registrations here
 */
The file makeswift/components.ts should be imported wherever you use <ReactRuntimeProvider> in your app.

​
Icons List

Here is the list of available icons to use when registering your component.
billing
bolt
button
carousel
chats
code
countdown
cube
database
divider
form
gallery
help
image
layout
lock
navigation
social-links
star
text
users
video
⌘I