Skip to main content

Custom Components

Join the Beta

For early access to the Custom Components private beta, enter your email to join the waitlist

Overview

Superblocks makes it easy to bring your own React components into the application builder. Register new components to any app, or create a library of components that's shared across your entire organization. Superblocks gives you the power of React right in our application builder alongside drag and drop, allowing you to build applications fast while reusing your existing components.

Custom components are developed locally on the developer’s machine and then uploaded to Superblocks for hosting. You add a custom properties panel to your components so that other developers can easily interface with custom components identically to built-in components.

Custom components can either be:

  1. Scoped to a single application
  2. Scoped to your organization - components can be packaged and published as a Library for reuse across multiple applications

Custom components show up in your components list just like all other Superblocks components. Within your app you can have multiple components that are available at the latest version. Component libraries that are shared across your organization must be installed first, which pins it to a specific version - this lets your team have full control over the dependent version.

In this tutorial, you will build a custom 5-star ratings component by using a third-party components library, Material UI.

Final 5-star rating component

Creating a Custom Component in React

Creating a custom component in Superblocks takes only 5 steps:

  1. Install the Superblocks CLI
  2. Define your custom Superblocks properties panel (how users will interact with your component in the application builder)
  3. Start your local development server and connect it to Superblocks
  4. Build your component
  5. Upload it to Superblocks!

1. Install the Superblocks CLI

The Superblocks CLI is responsible for:

  1. Running a local development server that Superblocks can connect to in order to display your component in your application
  2. Bundling and uploading your code to Superblocks for hosting

Installing the CLI is as straightforward as:

$ npm install -g @superblocks/cli

Once it is installed, run the following command to receive an authentication token:

$ superblocks login

Initialize your application folder by running:

$ superblocks init

When prompted, supply the application URL of the application to which you would like to add a custom component.

The Superblocks Application Directory

You will now have a default application folder setup for you with the following structure:

MyApplication/  # root application folder
package.json # package file for third party libs and sb libs
superblocks.config.ts # root config file, this is the entry point
ExampleComponent/ # pre-initialized counter custom component
config.ts # represents the properties pane for the component
ExampleComponent.tsx # holds the actual React code that runs

2. Create & Configure your component’s Properties Panel

Let’s bring in the Material Design Rating component into Superblocks. First, you must choose what properties you would like to expose developers using your custom component. There are two main categories of properties you can add to the properties panel:

info

Stateful properties represent the state of the component and what fields show up in the properties panel.

info

Event handlers specify the types of events the component can fire.

In the case of a Ratings component, it has two main properties:

  1. Rating - the rating that the component displays (this is a stateful property)
  2. OnChange - the event that is fired when the rating is changed (this is an event handler)

The final properties panel should look like the following:

Properties Panel for Ratings component

Use the Superblocks CLI to create the component:

$ superblocks create component

> Component Name: MyRatingsComponent
> Component machine-readable name: rating
> Component config file (default: Rating/config.ts, press enter to use default):
> Component main file (default: Rating/component.tsx, press enter to use default):
> Stateful Properties: rating
> Input type (Dropdown, Text, etc.): Text
> Add another stateful property (y/n)? n
> Event Handlers: onChange
> Add another event handler (y/n)? n
...
Congratulations! Your component has been initialized, refresh your Superblocks application to see the Ratings component in your components list.

Running this command will generate the following folder in your application with a config.ts file that represents the properties panel based on the prompts we just answered.

Rating/
config.ts
component.tsx

Refresh your editor, and you will see the Rating component listed in the components list. You can now drag this onto the Superblocks canvas.

Properties Panel for Ratings component

3. Start your local development server and connect it to Superblocks

Once you're ready to start editing your component, use the Superblocks local development mode

To begin seeing your work in the UI, run the watch command. This will run a local development server so you can see live updates.

info

The local development server affects all components in the same directory, so you can edit any component.

superblocks watch

While the watch command is running, click the header and select "Local dev mode". This will begin using your development server. Try typing a new value inside the React file and it will update instantly.

How to turn on Local Development mode

4. Editing the React Code that powers your Custom Component

Add the Material UI library to package.json using npm

$ npm install –-save @mui/material

Open an editor to edit Rating/component.tsx and begin connecting that to Superblocks functionality. Superblocks will render your component. Replace the default component with:

import React from "react";
import Rating from "@mui/material/Rating";
import type { ComponentProps } from "@superblocks/extensions";

export default function Rating({ stateProps, eventHandlers, setStateProp }: ComponentProps) {
return (
<Rating
value={stateProps?.rating ?? null}
onChange={(event, newValue) => {
setStateProp("rating", newValue);
eventHandlers.onChange();
}}
/>
);
};

In the UI, you should now see a fully functioning Rating component!

Final ratings component with unconfigured properties panel

Add a test event handler to show an alert when you change the rating:

Final ratings component

5. Upload your component to Superblocks

When you are done developing locally, your local changes are not yet uploaded to Superblocks. To upload your changes so that they are available for other users:

Run the upload command from the CLI:

$ superblocks upload

Finally remember to:

  1. Turn off Local Development mode in the UI
  2. Verify your latest changes and deploy your app!

Congratulations, you have successfully imported your own component into Superblocks!

Workaround

While you do not have access to the beta, the Superblocks iFrame Component can be used to display custom HTML and retrieve data from it. Find out how to create a custom color picker here.