)}
;
};
## Arguments
1.
Your component to be registered. This can be a React component or a function.
2.
Options for site version and locale.
A unique string that identifies the component for Makeswift to
render. Don't change the type once you use the component in
the Makeswift builder.
If this value changes after you use the component in the Makeswift builder, the component will appear as a "Component not found" block. To fix this, restore the `type` to the original value, or delete this component and re-add add it to the page.
The label shown in the Makeswift builder.
The description shown in the Panel of the Makeswift builder. This can be written in Markdown format.
Added in [`v0.24.8`](https://github.com/makeswift/makeswift/releases/tag/%40makeswift%2Fruntime%400.24.8).
The icon shown in the Makeswift builder. You can find all available icons in the [icons list](#icons-list) section.
A boolean that determines whether or not this component will be displayed in the Component Tray.
A boolean that determines whether or not this component will be wrapped in a built-in `` boundary.
Defaults to `true`. Set this to `false` if your component already includes its own `` boundary.
Added in [`v0.26.0`](https://github.com/makeswift/makeswift/releases/tag/%40makeswift%2Fruntime%400.26.0).
An object mapping prop names to Makeswift [controls](/developer/concepts#controls).
## 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`](/developer/reference/controls/style) control to the
`className` prop.
```tsx makeswift/components.tsx theme={null}
import { Style } from "@makeswift/runtime/controls";
import { runtime } from "./runtime";
function Box({ className }) {
return
I'm a box!
;
}
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:
```tsx makeswift/components.tsx theme={null}
import { Style } from "@makeswift/runtime/controls";
function Cube({ className }) {
return
Cube!
;
}
function Sphere({ className }) {
return
Sphere!
;
}
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 `` boundary to
transparently enable efficient server-side streaming and asynchronous data fetching. If your component
already includes its own `` boundary, you can disable the built-in one by setting the
`builtinSuspense` option to `false`:
```tsx theme={null}
import { TextInput } from "@makeswift/runtime/controls";
import { runtime } from "./runtime";
function Discography({ artistId }: { artistId?: string }) {
return (
<>
Discography
{/* component's own Suspense boundary with a fallback */}
Loading...}>
);
}
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](#icons-list) section.
In the builder
component tray, we can see our component with the selected icon.
```tsx makeswift/components.tsx theme={null}
import { Style } from "@makeswift/runtime/controls";
import { ComponentIcon } from "@makeswift/runtime";
import { runtime } from "./runtime";
function ImageGallery({ className }) {
return
I'm an image gallery!
;
}
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.
```typescript theme={null}
const mdDescription = `
# This is a larger heading
This is some text at the top of here
[](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 \`\`\`\`
`
```
```tsx makeswift/components.tsx theme={null}
import { Style } from "@makeswift/runtime/controls";
import { runtime } from "@/makeswift/runtime";
function Circle({ className }) {
return
I'm a circle!
;
}
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.
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.
```tsx components/Box/Box.tsx theme={null}
interface Props {
className?: string;
}
function Box({ className }) {
return
I'm a box!
;
}
```
```tsx components/Box/Box.makeswift.ts theme={null}
import { Style } from "@makeswift/runtime/controls";
import { runtime } from "@/makeswift/runtime";
import { Box } from "./Box";
runtime.registerComponent(Box, {
type: "box",
label: "Box",
props: {
className: Style({ properties: Style.All }),
},
});
```
Then update your `makeswift/components.tsx` file to import all of the component registrations, like so:
```ts makeswift/components.ts theme={null}
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 [``](/developer/reference/components/react-runtime-provider) in your app.
## Icons List
Here is the list of available icons to use when registering your component.
```tsx makeswift/components.tsx theme={null}
import { Style } from "@makeswift/runtime/controls";
function Cube({ className }) {
return 
```tsx makeswift/components.tsx theme={null}
import { Style } from "@makeswift/runtime/controls";
import { ComponentIcon } from "@makeswift/runtime";
import { runtime } from "./runtime";
function ImageGallery({ className }) {
return 
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.