Elements are the smallest content units a user can add directly in the admin page builder. They live inside sections, items, and other elements (via the Container element), and represent individual visual or interactive pieces such as headings, text, images, links and forms.
Users add them with the "Add element" menu, and each element's settings appear in the sidebar when it is selected. Elements are shared across themes: the ElementType enum, settings and data live in v4-lib, while each theme decides how to render each type via its own SectionElement component (a switch on element.type). A theme only needs a case for the types it supports. See Sections for the components used to render and lay out elements within a section.
Most element types are self explanatory and need no theme specific setup beyond a case in SectionElement.
| Type | Notes |
|---|---|
| Heading | Renders a heading. The level (h1 to h6) is configurable. |
| Text | A rich text block. |
| Link / Button | A link, styled as a button or a text link via its button variant. |
| Image | A single image. Use the lib ImageElement so URLs route through the image cache. |
| Video | An embedded video. |
| Social | A set of social media links. |
| Divider | A simple horizontal rule. |
| Search Form | The property search form, using the theme's global search configuration. |
| Branch search form | A search form scoped to branches. |
| Container | Groups child elements and controls their flex layout, allowing nested layouts. |
| Form | A lead or custom form. See Form element below. |
The Form element lets a client place a lead form inside any section, so a form can sit alongside other elements (for example next to a CTA) rather than filling the full width of a Custom Form section.
It renders one of two kinds of form:
/form_submissions. See Lead Submissions for the underlying submit flow.The shared logic lives in v4-lib: the built-in form registry, the admin settings, and the useFormElement hook. Each theme only provides the render component.
Add a case to the theme's SectionElement switch:
import { ElementType } from '@homeflow/v4-lib/state';
case ElementType.Form:
return <FormElement element={element} editMode={editMode} />;
The render component uses useFormElement, which resolves the configured form and returns everything needed to render and submit it:
import useFormElement, { Status } from '@homeflow/v4-lib/hooks/use-form-element';
const { kind, builtInForm, selectedForm, status, onSubmit } = useFormElement(element.form);
kind is 'builtIn', 'custom' or 'none'.builtInForm.fields describes the fields to render for a built-in form.selectedForm.form_elements describes the fields for a custom form (render these with FormElementControl and your theme's custom form field component, as the Custom Form section does).onSubmit is passed to react-hook-form's handleSubmit. It wraps submitLeadForm, so recaptcha, GA events and marketing metadata are handled for you. Built-in forms post to the matching lead action; custom forms post to /form_submissions.status (Status.Loading / Status.Success) drives the sending and success states.Use the theme's own field components (Input, Textarea, Select, MarketingPreferences, Button) so the form matches the theme's styling.
The settings sidebar is shared, so themes get it automatically. It starts with a form type dropdown listing the built-in forms plus the agency's custom forms. Branch Enquiry also shows an optional Branch selector, which routes leads to a specific branch or, when left empty, to the default agency.
Built-in forms are defined in form-elements/built-in-forms.ts. To add one, add its key to BUILT_IN_FORM_KEYS and an entry to builtInForms with its label, fields, and a submit action from @homeflow/v4-lib/actions:
branch_enquiry: {
key: 'branch_enquiry',
label: 'Branch Enquiry',
fields: [
{ name: 'firstName', placeholder: 'first name', control: 'text', required: true },
// ...
],
submit: (params) => submitBranchEnquiryLead(params as BranchEnquiryParams),
},
Field name values must match the lead param keys so the collected values pass straight to the submit action. No hook or theme changes are needed; the new form appears in the dropdown and submits automatically.