Getting started

Introduction

What rcube-html is, how to install it and how to build your first schema-driven form.

What is rcube-html?

rcube-html builds React + Bootstrap pages from a schema: a plain list of objects that says what to show — rows, columns, text, form fields, tables, charts, a calendar, file uploads, trees and more.

You write the schema (it is JSON, so it can also come from an API or a database) and a few small functions called actions. The library does the rest: layout, validation, error messages, values, events and translation.

How to read these tutorials

Pick a topic in the contents on the left (or search with /).
Try it: every page has a live example. Its Events box shows each action that runs and the data it receives.
Copy it: the Code box has the schema, the actions and a Full page.js that you can paste into your app and run as is.

1. Install

In a Next.js (or any React) app:

npm install rcube-html react-bootstrap bootstrap

2. Add Bootstrap's CSS once

In Next.js, import it in app/layout.js:

import "bootstrap/dist/css/bootstrap.min.css";

3. Write a schema and render it

useDynamicTag({ schema, actions, onSubmit }) creates the form; <DynamicTag form={form} /> draws it. The page must be a client component ("use client").

The example below is a complete sign-up form: two required fields, an email pattern, and two buttons that call the built-in actions clearForm() and runValidation(). Press Submit with empty fields, then fill them in and press it again.

Try it

Loading example…

Events0

Use the example — every action it runs shows up here with its data.

Code

Copy Full page.js into app/your-page/page.js of a Next.js app (withrcube-html, react-bootstrap and Bootstrap's CSS installed) — it runs as is. Or copy only the schema and keep your own page.

[
  {
    "type": "row",
    "id": "row-title",
    "children": [
      {
        "type": "column",
        "id": "col-title",
        "children": [
          {
            "type": "H4",
            "id": "title",
            "props": {
              "text": "Sign up"
            }
          }
        ]
      }
    ]
  },
  {
    "type": "row",
    "id": "row-fields",
    "children": [
      {
        "type": "column",
        "id": "col-name",
        "props": {
          "className": "col-12 col-md-6"
        },
        "children": [
          {
            "type": "InputField",
            "id": "first",
            "props": {
              "name": "firstName",
              "label": "First name",
              "required": true,
              "uppercase": true
            }
          }
        ]
      },
      {
        "type": "column",
        "id": "col-email",
        "props": {
          "className": "col-12 col-md-6"
        },
        "children": [
          {
            "type": "InputField",
            "id": "email",
            "props": {
              "type": "email",
              "name": "email",
              "label": "Email",
              "required": true,
              "lowercase": true,
              "pattern": "[^\\s@]+@[^\\s@]+\\.[^\\s@]{2,}",
              "patternMessage": "Please enter a valid email address."
            }
          }
        ]
      }
    ]
  },
  {
    "type": "row",
    "id": "row-buttons",
    "children": [
      {
        "type": "column",
        "id": "col-buttons",
        "props": {
          "className": "d-flex justify-content-end gap-2"
        },
        "children": [
          {
            "type": "ButtonField",
            "id": "clear",
            "props": {
              "text": "Clear",
              "onClick": "clearForm()"
            }
          },
          {
            "type": "ButtonField",
            "id": "submit",
            "props": {
              "type": "submit",
              "text": "Submit",
              "onClick": "runValidation()"
            }
          }
        ]
      }
    ]
  }
]

Options used here

Option	What it does
`type`	What to draw: `row`, `column`, `InputField`, `ButtonField`, `H4`, ...
`id`	A unique name for every node. Actions use it to change that node later.
`props.name`	The field's key in the submitted values (`firstName`).
`props.required`	The field must be filled in before Submit works.
`props.uppercase / lowercase`	Change the letters while the user types.
`props.pattern / patternMessage`	A regular expression the value must match, and the message when it does not.
`props.onClick`	The action a button runs. `runValidation()` and `clearForm()` are built in.

Events

Event	When it runs	Your action receives
`onSubmit`	Submit is pressed and every visible field is valid.	An array with one object of values per entry: `[{ firstName: "JANE", email: "jane@example.com" }]`.

Tips

The schema is data, so you can load it with fetch and pass it to useDynamicTag.
Next: Schema basics explains rows, columns and ids.