📦 @livepreso/react-plugin-textfield

Components

TextField

Unmanaged rich text editor. The parent component is responsible for providing the value and handling changes via onChange.

import React, { useState } from "react";
import { TextField } from "@livepreso/react-plugin-textfield";

export default function () {
	const [value, setValue] = useState("<p>Hello world</p>");
	return (
		<TextField
			value={value}
			onChange={setValue}
			textStyles={[
				{ block: 0, title: "Body" },
				{ block: 1, title: "Heading 1" },
			]}
		/>
	);
}

Props:

Prop Name	Type	Description
value	String	HTML string value for the editor.
onChange	Function	Called with the updated HTML string on each change.
tag	String	Constrains the editor to a specific HTML block type (p, h1–h6). See tag.
isReadOnly	Boolean	Disables editing. Defaults to false.
className	String	Additional CSS class applied to the editor wrapper.
textStyles	Array	Text style options for the heading selector. See textStyles.
colors	Array	Colour swatches for the text colour picker. See colors.
toolbarConfig	Array	Ordered list of toolbar group IDs to display. Defaults to DEFAULT_TOOLBAR_CONFIG. See Toolbar.
tableToolbarConfig	Array	Ordered list of table toolbar group IDs. Defaults to DEFAULT_TABLE_TOOLBAR_CONFIG. See Toolbar.
tokens	Array	Available tokens for insertion. See tokens.
tokenConfig	Object	Additional options passed to the token extension. See tokens.
autofocus	Boolean	Focuses the editor on mount. Defaults to false.
extensions	Object	Custom Tiptap extensions keyed by name, merged with those derived from the toolbar config.
maskSelector	String	CSS selector used to position the toolbar relative to a masked container.
disableSpellcheck	Boolean	Disables browser spellcheck. Defaults to false.
children	Node	Rendered to an HTML string and used as the value if value is not provided.

ManagedTextField

Bridge managed rich text editor. Content is stored in CMS Vals (editable in PresoManager) when isCompany is set, and in the preso context (editable by the preso owner in prep mode) when isPrep is set. Both can be set simultaneously — in that case, the preso context value takes precedence during prep, falling back to the company-managed value when no per-preso edit exists.

At least one of isPrep or isCompany must be set, unless isReadOnly is true.

import React from "react";
import { ManagedTextField } from "@livepreso/react-plugin-textfield";

export default function () {
	return (
		<ManagedTextField id="body_text" isCompany={true} isPrep={true}>
			<p>Default text content.</p>
		</ManagedTextField>
	);
}

info

When isCompany is set, the id must be registered in the slide's editables list in project.yaml. See Project file — editables.

Props:

Prop Name	Type	Description
id	String	CMS Vals key for company-managed content, and default key for prep editable storage.
prepId	String	Override key for prep editable storage. Defaults to id.
tag	String	Constrains the editor to a specific HTML block type (p, h1–h6). See tag.
isCompany	Boolean	Enables company-managed editing in PresoManager. The id must be registered in project.yaml editables.
isPrep	Boolean	Enables per-preso editing in prep mode. Changes are saved to the preso context.
isReadOnly	Boolean	Disables editing. Defaults to false.
className	String	Additional CSS class applied to the editor wrapper.
textStyles	Array	Text style options for the heading selector. See textStyles.
colors	Array	Colour swatches for the text colour picker. See colors.
toolbarConfig	Array	Ordered list of toolbar group IDs to display. Defaults to DEFAULT_TOOLBAR_CONFIG. See Toolbar.
tableToolbarConfig	Array	Ordered list of table toolbar group IDs. Defaults to DEFAULT_TABLE_TOOLBAR_CONFIG. See Toolbar.
tokens	Array	Available tokens for insertion. See tokens.
tokenConfig	Object	Additional options passed to the token extension. See tokens.
autofocus	Boolean	Focuses the editor on mount. Defaults to false.
extensions	Object	Custom Tiptap extensions keyed by name, merged with those derived from the toolbar config.
maskSelector	String	CSS selector used to position the toolbar relative to a masked container.
disableSpellcheck	Boolean	Disables browser spellcheck. Defaults to false.
children	Node	Rendered to an HTML string and used as the default value.

Toolbar

The toolbar is configured via the toolbarConfig and tableToolbarConfig props, which accept ordered arrays of group ID constants. Groups are rendered left to right in the order they appear in the array.

Toolbar config constants are available from @livepreso/react-plugin-textfield/constants.

import React from "react";
import { ManagedTextField } from "@livepreso/react-plugin-textfield";
import { SIMPLE_TOOLBAR_CONFIG } from "@livepreso/react-plugin-textfield/constants";

export default function () {
	return (
		<ManagedTextField
			id="body_text"
			isCompany={true}
			toolbarConfig={SIMPLE_TOOLBAR_CONFIG}
		>
			<p>Default text.</p>
		</ManagedTextField>
	);
}

Pre-built configurations

Constant	Description
DEFAULT_TOOLBAR_CONFIG	Full set of primary toolbar groups. This is the default.
SIMPLE_TOOLBAR_CONFIG	Undo/redo, text style, tokens, and clear formatting.
MINIMAL_TOOLBAR_CONFIG	Undo/redo only.
COMPLETE_TOOLBAR_CONFIG	Alias for DEFAULT_TOOLBAR_CONFIG.
DEFAULT_TABLE_TOOLBAR_CONFIG	Full set of table toolbar groups. This is the default.
SIMPLE_TABLE_TOOLBAR_CONFIG	Delete table, column and row operations only.
COMPLETE_TABLE_TOOLBAR_CONFIG	Alias for DEFAULT_TABLE_TOOLBAR_CONFIG.

Toolbar groups

Primary toolbar groups (toolbarConfig):

Constant	Group ID	Contents
UNDO_REDO	"undo"	Undo, redo
BLOCK	"block"	Heading/block type selector (requires textStyles)
TEXT_STYLE	"text-style"	Bold, italic, underline, text colour, superscript, subscript
ALIGNMENT	"alignment"	Left, centre, right, justify
LINK	"link"	Insert/edit link, remove link
TOKEN	"token"	Insert token (only visible when tokens is non-empty)
LIST	"list"	Bullet list, ordered list
TABLE	"table"	Insert table
CLEAR_FORMATTING	"clear-formatting"	Clear all formatting

Table toolbar groups (tableToolbarConfig):

Constant	Group ID	Scope	Contents
TABLE_SIZE	"tableSize"	Table-wide	Full width, equal column widths
DELETE_TABLE	"deleteTable"	Table-wide	Delete table
COLUMN	"column"	Cell menu	Add column left/right, remove column
ROW	"row"	Cell menu	Add row above/below, remove row
CELL	"cell"	Cell menu	Merge cells, split cells, cell background colour, cell vertical alignment

Table-wide groups appear in a toolbar below the focused table. Cell menu groups appear in a contextual menu within the focused cell.

textStyles

The textStyles prop accepts an array of style objects that populate the heading/block type selector in the toolbar (BLOCK group). Each object has:

Key	Type	Description
block	Number	The block level. 0 = paragraph, 1-6 = heading level.
title	String	Label shown in the toolbar dropdown.

const textStyles = [
	{ block: 0, title: "Body" },
	{ block: 1, title: "Title" },
	{ block: 2, title: "Heading" },
	{ block: 3, title: "Subheading" },
];

info

The BLOCK group must be included in toolbarConfig for the selector to appear.

colors

The colors prop accepts an array of hex colour strings used to populate the swatches in the text colour picker.

const colors = ["#000000", "#ffffff", "#cc0000", "#1a73e8"];

info

The TEXT_STYLE group must be included in toolbarConfig for the colour picker to appear.

tokens

Tokens are dynamic named values that can be inserted into the field by the user. They are displayed as inline nodes that render their value at runtime.

The tokens prop accepts an array of token objects:

Key	Type	Description
id	String	Unique identifier for the token.
label	String	Label shown in the token picker and as a placeholder in editable mode.
description	String	Optional description shown in the token picker.
render	Function	Returns the token's rendered string value.
options	Object	Optional per-token configuration (e.g. { burstOnCreate: true }).

const tokens = [
	{
		id: "customer_name",
		label: "Customer name",
		description: "The customer's full name",
		render: () => context.customer.name,
	},
];

info

An array must be supplied to the tokens prop, as well as the TOKEN group included in toolbarConfig for the insert button to appear. The Token extension is always registered when tokens is non-empty, so existing token nodes render correctly regardless of whether the insert button is shown.

tokenConfig

The tokenConfig prop accepts additional options passed to the Token extension at the field level:

Key	Type	Description
burstOnCreate	Boolean	When true, the token node is immediately replaced with its rendered text value on insertion. Useful in modes where tokens should not persist as interactive nodes.

tag

The tag prop constrains the editor's document type to a specific HTML block element. When set, users cannot switch between block types. Supported values: p, h1-h6. Defaults to div when omitted.

// Editor can only contain paragraph content
<TextField tag="p" ... />

// Editor locked to h2 content
<TextField tag="h2" ... />

note

Text format switching (ie. block types) is only available when the editable tag is a div.