Building a Card Component in Makeswift

Learn how to create a built-in card component that integrates with Makeswift.

As opposed to components that are created in the Visual Builder, built-in components are React components that are registered and integrated with Makeswift from code. As expected, these are available to users in the Visual Builder to use while building layouts and pages. Let’s see how to create and register a built-in component.

Prerequisites

This guide assumes that you are using TypeScript and have followed the App Router Installation guide for your initial project setup. It also assumes you are using a src directory.

If your setup varies from this, please adjust the code snippets appropriately.

Overview

In this guide, we’re going to build a Card component that can be used to display product data. This component will need a few different properties:

• image - the URL of the image
• alt - the alt text to use for the image
• heading - the heading text
• description - the description text
• link - the link to navigate to
• linkText - the text of the link

In general, creating built-in components in Makeswift requires two things:

1. A React component
2. A file that registers the component with Makeswift

When registering a component with Makeswift, you also define all of the properties that should be editable in the Visual Builder. These properties are defined using Makeswift controls and will map to the props your React component expects.

Creating the React component

Start by creating a src/components/Card directory and add an index.tsx file. Then, define a type for the component props based on our requirements.

1
type CardProps = {
2
  className?: string;
3
  image?: string;
4
  alt: string;
5
  heading: string;
6
  description: string;
7
  link: { href: string; target?: "_blank" | "_self" };
8
  linkText: string;
9
};

All of these properties will match the properties that the user can edit in the Visual Builder by way of Makeswift controls. We’ll explore this more in the registering the component section, but the result will look like this.

Next, we can define the component itself. In this example, we’ll be using the Link and Image components from Next.js. Ignoring styles, the final component will look like this.

1
import Link from "next/link";
2
import Image from "next/image";
3
4
type CardProps = {
5
  className?: string;
6
  image?: string;
7
  alt: string;
8
  heading: string;
9
  description: string;
10
  link: { href: string; target?: "_blank" | "_self" };
11
  linkText: string;
12
};
13
14
export function Card({
15
  className,
16
  image,
17
  alt,
18
  heading,
19
  description,
20
  link,
21
  linkText,
22
}: CardProps) {
23
  return (
24
    <div className={className}>
25
      {image && <Image src={image} alt={alt} objectFit="cover" fill />}
26
      <div>
27
        <h3>{heading}</h3>
28
        <p>{description}</p>
29
        <Link href={link.href} target={link.target}>
30
          {linkText}
31
        </Link>
32
      </div>
33
    </div>
34
  );
35
}

Registering the component

After creating the React component, we need to register that component with Makeswift. This makes the component available in the Component Tray for users to drag onto the canvas.

This is also where/how we define the properties that are exposed to the user in the Visual Builder that match the properties we just defined in the React component.

To register a component, we’ll need to call registerComponent from an instance of the ReactRuntime. If you followed the Installation guide, you should have an instance of the ReactRuntime defined in src/makeswift/runtime.ts.

When calling, registerComponent, you’ll need to pass the React component to be registered as well as a config object with three required properties:

• type - a unique identifier for the component
• label - the label that shows up in the Visual Builder
• props - an object mapping of prop names to Makeswift controls

We can register our component like so:

1
import { runtime } from "src/makeswift/runtime";
2
import { Card } from "./";
3
4
runtime.registerComponent(Card, {
5
  type: "product-card",
6
  label: "Product Card",
7
  props: {},
8
});

Adding an icon

Additionally, you can include an optional icon property in your configuration object to specify which icon to be displayed along side your component. In this example, we’ll use the image icon.

1
import { runtime } from "src/makeswift/runtime";
2
import { Card } from "./";
3
4
runtime.registerComponent(Card, {
5
  type: "product-card",
6
  label: "Product Card",
7
  icon: 'image'
8
  props: {},
9
});

Refer to the Icons List for a full list of options.

Defining props

At this point, you should see an error in your editor on the reference to the Card component. This is because we set props to be an empty object. However, props should be a mapping of properties to Makeswift controls that match the props the Card component expects.

If we update props accordingly, this error will go away.

Note also that as we define each of these, we’ll need to import the appropriate control from @makeswift/runtime/controls. We’ll skip this for now, but each import is included in the final registration code for your reference.

Adding a Style control

We can start by using the Style control which allows our component to receive styles that are defined by the user in the Visual Builder. To do this, add a key of className to the props object with a value of Style(). Notice that className matches the name of the prop that our component is expecting. We’ll make sure to match this for each prop we define here.

1
props: {
2
  className: Style();
3
}

By default the Style controls allows the user to edit the width and margin for a component.

Additionally, you can manually select which properties you want to be visually editable by passing an object with a properties property like so:

1
props: {
2
  className: Style({ properties: [Style.Width, Style.Margin] });
3
}

Each Makeswift control has its own set of configuration options. You can check the documentation for full details on each one. We’ll keep the default in this example, but for full details, refer to the docs for the Style control params.

Adding a Image control

For the image property, we can use the Image control.

1
props: {
2
  // ...other props
3
4
  image: Image(),
5
}

By default, the Image control will pass the URL of the image as a string to the React component. However, it can also return an object that includes width and height properties like so:

1
{
2
  url: string;
3
  dimensions: {
4
    width: number;
5
    height: number;
6
  }
7
}

You can configure this by passing a configuration object with format property set to Image.Format.WithDimensions.

1
const props = {
2
  // ...other props
3
4
  image: Image({
5
    label: "Image",
6
    format: Image.Format.WithDimensions,
7
  }),
8
};

For now, though, we’ll use the default output of a string.

Adding TextInput controls

For the heading property, we can use the TextInput control.

1
props: {
2
  heading: TextInput({ label: "Heading", defaultValue: "My Heading" }),
3
}

Notice we are defining a defaultValue here. Because the heading prop in our Card component is marked as required, we must provide the defaultValue. In general, how you define your props in Makeswift should match the interface you’ve defined in your React component.

Let’s continue by adding two more TextInput controls for alt and linkText. Again, we’ll set label and defaultValue for both.

1
props: {
2
  // ...other props
3
4
  alt: TextInput({
5
    label: "Image alt text",
6
    defaultValue: "",
7
  }),
8
  linkText: TextInput({ label: "Link text", defaultValue: "Read more" }),
9
}

Adding a TextArea control

For the description, we want to allow the user to input a larger piece of text, so we can use the TextArea control.

1
props: {
2
  // ...other props
3
4
  description: TextArea({
5
    label: "Description",
6
    defaultValue: "My description",
7
  }),
8
}

Adding a Link control

Lastly, we can use the Link control for the link prop.

1
props: {
2
  // ...other props
3
4
  link: Link({ label: "Link" }),
5
}

By default, this controls passes the object type we are expecting in our Card component which is an object that includes href and target properties.

Final registration code

After putting all of these properties together, you’ll get something like this.

1
import { runtime } from "src/makeswift/runtime";
2
import { Card } from "./";
3
import {
4
  TextInput,
5
  Image,
6
  TextArea,
7
  Link,
8
  Style,
9
} from "@makeswift/runtime/controls";
10
11
runtime.registerComponent(Card, {
12
  type: "product-card",
13
  label: "Product Card",
14
  icon: "image",
15
  props: {
16
    className: Style(),
17
    image: Image(),
18
    alt: TextInput({
19
      label: "Image alt text",
20
      defaultValue: "Description of the image",
21
    }),
22
    heading: TextInput({ label: "Heading", defaultValue: "My Heading" }),
23
    linkText: TextInput({ label: "Link text", defaultValue: "Read more" }),
24
    description: TextArea({
25
      label: "Description",
26
      defaultValue: "My description",
27
    }),
28
    link: Link({ label: "Link" }),
29
  },
30
});

Importing the component

After creating and registering the component, we need to make sure that Makeswift is aware of it by importing it in three different places.

• the root layout.tsx file
• the Makeswift provider in the src/makeswift/provider.tsx file
• the dynamic API route in src/app/api/makeswift/[...makeswift].ts

If you’ve followed the Installation guide for initial setup, you should have a src/makeswift/components.ts file which is already imported into each of these three places. In this case, you can import your registration file here, and you’ll be good to go.

1
// ...other component imports
2
3
import "src/components/Card/Card.makeswift";

If you didn’t follow the installation guide, you’ll need make sure the new component is imported in those three places manually.

Final result

To be able to see your component within the Visual Builder, you’ll need your Makeswift site to be connected to your locally running application. Again, follow the Installation guide for details on how to do that if you aren’t already set up.

Assuming your Makeswift site is connected, after refreshing the page, you should see your component listed in the Component Tray.

Then, after dragging an instance of your component onto the Canvas and filling out the details, you should see your card in action.