Blocksweb developer docs

Appearance

What is an Option ​

Options in blocksweb are one of the most important aspects of Blocksweb, they allow the developer to control what the end-user is allowed to modify, options are passed down to the react component as props and are to be handled by the developer.

Adding your first option ​

tsx
import React from "react";
import { IBlockswebComponent } from "@blocksweb/core";

type SectionComponentProps = {
  title: string;
};

const SectionComponent: IBlockswebComponent = (
  props: SectionComponentProps
) => {
  return <div>{props.title}</div>;
};

SectionComponent.schema = {
  displayName: "SectionComponent",
  options: [
    {
      type: "text",
      name: "title",
      label: "Title",
      default:
        "This is the text that is displayed before the end-user changes it",
    },
  ],
};

export default SectionComponent;

Option Types ​

Options in Blocksweb are predefined types that allow users to configure various attributes of a component. Each option type has specific attributes.

Text ​

Displays simple text on the screen.

Attributes:

  • type: text
  • name: The property name associated with this option.
  • label: The name displayed in the editor for this option.
  • default: The initial text value before any changes are made.

Example:

tsx
{
  type: "text",
  name: "headerText",
  label: "Header Text",
  default: "Welcome to our website",
}

Number ​

Displays a numerical value on the screen.

Attributes:

  • type: number
  • name: The property name associated with this option.
  • label: The name displayed in the editor for this option.
  • default: The initial numerical value before any changes are made.

Example:

tsx
{
  type: "number",
  name: "maxItems",
  label: "Maximum Items",
  default: 5,
}

Query ​

Enables dynamic querying of the CMS to retrieve and display data from your database.

Attributes:

  • type: query
  • name: The property name associated with this option.
  • label: The name displayed in the editor for this option.
  • default: Default value is null.

Example:

tsx
{
  type: "query",
  name: "productsList",
  label: "Products Query",
  default: null,
}

Rich Text ​

Allows users to insert and format rich text within the component. This is integrated with the RichText utility.

Attributes:

  • type: richtext
  • name: The property name associated with this option.
  • label: The name displayed in the editor for this option.
  • default: The initial rich text content before any changes are made.

Example:

tsx
{
  type: "richtext",
  name: "description",
  label: "Product Description",
  default: "<p>Enter your product description here</p>",
}

Image ​

Lets end-users upload images directly within the editor or through the Asset Manager.

Attributes:

  • type: image
  • name: The property name associated with this option.
  • label: The name displayed in the editor for this option.
  • default: The URL of the default image if no changes are made.

Example:

tsx
{
  type: "image",
  name: "headerImage",
  label: "Header Background",
  default: "https://example.com/default-header.jpg",
}

Component ​

Allows users to select a Blocksweb component within another Blocksweb component. This type is unique and facilitates advanced component nesting.

Attributes:

  • type: component
  • name: The property name associated with this option.
  • label: The name displayed in the editor for this option.

Example:

tsx
{
  type: "component",
  name: "sidebar",
  label: "Sidebar Component",
}

Combining Multiple Options ​

When building complex components, you'll often need to combine multiple option types:

tsx
const ProductCard: IBlockswebComponent = (props) => {
  // Component implementation
};

ProductCard.schema = {
  displayName: "Product Card",
  options: [
    {
      type: "text",
      name: "title",
      label: "Product Title",
      default: "Product Name",
    },
    {
      type: "number",
      name: "price",
      label: "Product Price",
      default: 99.99,
    },
    {
      type: "image",
      name: "productImage",
      label: "Product Image",
      default: "https://example.com/default-product.jpg",
    },
    {
      type: "richtext",
      name: "description",
      label: "Product Description",
      default: "<p>This is a high-quality product.</p>",
    }
  ],
};

See Also ​