/\  Semaphor

Custom Components

Learn how to render custom components in Semaphor dashboard

Overview

When embedding analytics into your app, you'll often need to display information in industry-specific ways. For example:

  • Trade analytics: A specialized map to visualize imports and exports between countries.
  • Financial apps: A table with precise sorting and filtering options.
  • HR tools: A distribution chart to show candidate demographics.

The sheer variety of visualizations means no single charting library can cover every need. Most BI tools lock you into one or two libraries, offering only limited customization.

This creates a tough choice:

  1. Settle for generic charts, leading to a subpar user experience.
  2. Build everything in-house, investing time and resources in analytics infrastructure instead of your core product.

As your analytics needs evolve, rigid BI tools make it increasingly difficult to adapt. That’s why flexibility is crucial when choosing an embedded analytics solution.

At Semaphor, we’ve designed a pluggable architecture that lets you bring your own charting library—or even fully custom components. This gives you complete control over the user experience, enabling you to integrate interactive, custom visuals with just a few lines of code.

Let's take a look at how it works.

Step 1: Create your custom component

The repository below includes a basic example of how to create a custom component for Semaphor.

Clone the repository
git clone https://github.com/rohitspujari/semaphor-plugin-quickstart.git
cd semaphor-plugin-quickstart
npm install
npm run dev

This starts a local server at http://localhost:5173. You can open up this repository in your favorite code editor and start exploring the code.

In semaphor-components folder, you'll find the custom component that we'll add to the Semaphor dashboard. It's a simple component showing recent sales — about 50 lines of code. It takes a data prop, which is the data to be displayed. But you can make your components as sophisticated as you want.

src/components/semaphor-components/recent-sales-card.tsx
import { SingleInputVisualProps } from '../types';
 
export function RecentSales({ data }: SingleInputVisualProps) {
  if (!data || data?.length === 0) return null;
 
  // get the column keys of the data
  const keys = Object.keys(data[0]);
 
  // calculate the total sales
  const totalSales = data.reduce(
    (acc, record) => acc + Number(record?.[keys[2]]),
    0
  );
  // format total sales to 2 decimal places and add $ with commas
  const formattedTotalSales = totalSales
    .toFixed(2)
    .replace(/\B(?=(\d{3})+(?!\d))/g, ',');
 
  return (
    <div className="px-4 bg-background rounded-lg">
      <h2 className="text-lg font-semibold">Recent Sales</h2>
      <p className="text-sm text-muted-foreground mb-4">
        You made {formattedTotalSales} sales this month.
      </p>
      <ul className="p-0">
        {data.map((record, index) => (
          <li
            key={index}
            className=" flex items-center justify-between py-2 border-b border-muted last:border-none"
          >
            <div className="flex items-center">
              <div className="w-10 h-10 bg-muted rounded-full flex items-center justify-center text-black font-bold">
                {record[keys[0]]
                  ?.toString()
                  .split(' ')
                  .map((n) => n[0])
                  .join('')}
              </div>
              <div className="ml-3">
                <p className="font-medium text-foreground">
                  {record?.[keys[0]]}
                </p>
                <p className="text-sm text-muted-foreground">
                  {record?.[keys[1]]}
                </p>
              </div>
            </div>
            <p className="font-semibold text-foreground">{record?.[keys[2]]}</p>
          </li>
        ))}
      </ul>
    </div>
  );
}

Once you are satisfied with your custom component, you need to export it as a named export in the index.ts file. You can export as many components as you want.

src/components/index.ts
import { RecentSales } from './semaphor-components/recent-sales-card';
 
import '../index.css';
 
export { RecentSales };

And lastly, you will need to specify how this component should appear in Semaphor console with components.config.ts file.

src/components/components.config.ts
export const config: ComponentsConfig = {
  visuals: [
    {
      name: 'Recent Sales', // The name of the component that will appear in the Semaphor dashboard
      icon: 'Table2', // The icon of the component
      component: 'RecentSales', // The component exported in the index.ts file
      settings: {
        label: {
          title: 'Label', // The label property of the component
          defaultValue: 'my label', // The default value of the label
          ui: 'input', // The UI type of the label property
        },
      },
    },
  ],
};

Step 2: Publish your component to Semaphor

To publish your component to Semaphor, you will first need to install semaphor-cli. You can do it with the following command:

Install semaphor-cli
npm install -g semaphor-cli

Now let's initialize a new Semaphor Plugin for your custom component.

You will be prompted to enter your Semaphor project ID and secret. You can get them from your Semaphor project page.

NOTE: Make sure to initialize the Plugin and NOT the App.

Initialize the plugin
~/plugins/semaphor-plugin-quickstart semaphor init
? What do you want to publish? Plugin
? Enter your plugin name: my_first_plugin
? Enter your build path: dist
? Enter your Semaphor Project ID: p_315108f1-d76e-43ab-af8e-d88ccaae59fe
? Enter your Semaphor Project Secret: [hidden]
Config file created successfully!

Once the cli is initalized, you can build and publish your plugin to Semaphor with the following commands.

Build and publish your plugin
npm run build
semaphor publish

Step 3: Use your custom component in Semaphor Dashboard

You can now use your custom component in Semaphor dashboard just like any other visual from the visual selector and make it interactive with the rest of the dashboard.

Here is the sample dashboard with the custom component added. If you have any questions feel free to get in touch with us at support@semaphor.cloud

Previous

Best Practices

Next

React

On this page