Blocksweb Developer Docs

Appearance

Components & Schema ​

Learn how Blocksweb components work and how to define schemas that make them editable.

What is a Blocksweb Component? ​

A Blocksweb component is a React component with an attached schema that describes its editable properties.

typescript
import { IBlockswebComponent } from '@blocksweb/core';

const Hero: IBlockswebComponent = ({ title, subtitle }) => {
  return (
    <section>
      <h1>{title}</h1>
      <p>{subtitle}</p>
    </section>
  );
};

Hero.schema = {
  displayName: 'Hero Section',
  options: [
    { type: 'text', name: 'title', label: 'Title', default: 'Welcome' },
    { type: 'text', name: 'subtitle', label: 'Subtitle', default: 'Get started' },
  ]
};

export default Hero;

Component Anatomy ​

1. Component Function ​

The React component that renders your UI:

typescript
const Hero: IBlockswebComponent = (props) => {
  // Your component logic
  return <div>...</div>;
};

2. Schema Object ​

Defines how the component appears and behaves in the editor:

typescript
Hero.schema = {
  displayName: "Hero Section", // Name in component picker
  category: "Marketing", // Category grouping (optional)
  description: "Hero banner", // Description (optional)
  icon: "hero-icon", // Icon name (optional)
  options: [], // Editable properties
};

3. Options Array ​

Each option creates an editable property:

typescript
options: [
  {
    type: "text", // Input type
    name: "title", // Prop name
    label: "Hero Title", // Label in editor
    default: "Welcome", // Default value
    help: "Main page heading", // Help text (optional)
  },
];

Schema Properties ​

displayName (required) ​

typescript
displayName: "Hero Section";

How the component appears in the component picker.

category (optional) ​

typescript
category: "Marketing"; // or 'Content', 'Layout', 'E-commerce', etc.

Groups related components together in the picker.

description (optional) ​

typescript
description: "Large hero banner with title and call-to-action";

Shows additional information about the component.

icon (optional) ​

typescript
icon: "hero"; // Icon identifier

Custom icon for the component in the picker.

options (required) ​

typescript
options: [
  { type: "text", name: "title", label: "Title", default: "Welcome" },
  // More options...
];

Array of editable properties. See Options Reference for all types.

TypeScript Types ​

Use TypeScript for type-safe components:

typescript
import { IBlockswebComponent } from '@blocksweb/core';

type HeroProps = {
  title: string;
  subtitle: string;
  buttonText?: string;
  buttonUrl?: string;
};

const Hero: IBlockswebComponent<HeroProps> = ({
  title,
  subtitle,
  buttonText,
  buttonUrl
}) => {
  return (
    <section>
      <h1>{title}</h1>
      <p>{subtitle}</p>
      {buttonText && buttonUrl && (
        <a href={buttonUrl}>{buttonText}</a>
      )}
    </section>
  );
};

Hero.schema = {
  displayName: 'Hero Section',
  options: [
    { type: 'text', name: 'title', label: 'Title', default: '' },
    { type: 'text', name: 'subtitle', label: 'Subtitle', default: '' },
    { type: 'text', name: 'buttonText', label: 'Button Text', default: '' },
    { type: 'text', name: 'buttonUrl', label: 'Button URL', default: '' },
  ]
};

Best Practices ​

1. Provide Good Defaults ​

Always set default values so components look good immediately:

typescript
options: [
  {
    type: "text",
    name: "title",
    label: "Title",
    default: "Welcome to Our Website", // Good default
  },
];

2. Use Clear Names ​

Choose descriptive displayNames and labels:

typescript
// Good
displayName: "Hero Banner with CTA";
label: "Call to Action Button Text";

// Avoid
displayName: "Hero";
label: "CTA";

3. Group Related Options ​

Use categories to organize components:

typescript
// Marketing components
Hero.schema = { category: 'Marketing', ... };
CallToAction.schema = { category: 'Marketing', ... };

// Content components
RichText.schema = { category: 'Content', ... };
ImageGallery.schema = { category: 'Content', ... };

4. Add Help Text ​

Guide users with helpful descriptions:

typescript
{
  type: 'text',
  name: 'metaDescription',
  label: 'Meta Description',
  help: 'Keep between 150-160 characters for best SEO',
  default: ''
}

Next Steps ​