Building your first component

Custom components are based on React with some special properties to configure which ones you want to expose to the visual editor and how.

We provide a starter-component and the first thing we need is to clone the GitHub repo:

git clone git@github.com:sitecloudhq/starter-component.git

Now install all the required dependencies::

yarn install

Go into the cloned repo and list the directory. In the src directory you can find the code of your starter component and in stories you will find out an very basic story for Storybook. We use extensively Storybook here in Sitecloud to develop our own custom components and the built-in library but feel free to use whatever you prefer. For the seek of simplicity, we will keep using the provided story, execute now the next command:

yarn storybook

Storybook will get initiated and it will open your browser:

Nothing fancy, right? Let's try to make this more interesting, open src/starter.jsx in your favourite code editor. The next code will show up:

import React from "react";
import styled from "styled-components";
import { Component as Icon } from "@styled-icons/boxicons-solid";
import { PropTypes, EditorTypes } from "sitecloud-components";

const Container = styled.div`
  color: ${(props) => props.color || "black"};
`;

const Starter = ({ ...props }) => (
  <Container {...props}>This is your first component</Container>
);

Starter.props = {
  aspect: {
    color: {
      type: PropTypes.Color,
      default: "blue",
      editor: EditorTypes.Color,
      required: false,
      enabled: false,
    },
  },
};

Starter.icon = <Icon size="1.2rem" />;

export default Starter;

Starter is a functional component which is receiving some props. There is also a new property declared into this functional component named Starter.props, it is a object which define all the different props your component will received and how it will be exposed to the editor. In the specific case of the starter-component, this is what you would see in the visual editor:

Check the aspect prop, the starter-component is defaulting this to blue and typing it to EditorTypes.Color. Now lets use this color in our component. Go back to your code editor and modify the code as follow:

import { PropTypes, EditorTypes } from "sitecloud-components";

const Container = styled.div`
  background-color: ${(props) => props.color || "black"};
  color: white;
  padding: 1rem;
  text-align: center;
  border-radius: ${(props) => props.borderRadius};
`;

const Starter = ({ ...props }) => (
  <Container {...props}>Rounded borders</Container>
);

Starter.props = {
  aspect: {
    color: {
      type: PropTypes.Color,
      default: "blue",
      editor: EditorTypes.Color,
      required: false,
      enabled: false,
    },
  },
  borderRadius: {
    type: PropTypes.UnitValue,
    default: "0px",
    editor: EditorTypes.Slider,
  },
};

Starter.icon = <Icon size="1.2rem" />;

export default Starter;

We have added a new borderRadius property with a slider editor. Now you can publish, link to any of your projects and drop on any section you want:

Really cool! This is one the most powerful features of Sitecloud. Move now to the next tutorial to learn how to publish and use your component from the visual editor.