📦 @livepreso/react-plugin-textfield
Installing​
- npm
- Yarn
- pnpm
npm install @livepreso/react-plugin-textfield
yarn add @livepreso/react-plugin-textfield
pnpm add @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. |
| isScrollable | Boolean | Scrolls content that overflows the field instead of clipping it. See Scrolling. |
| maskSelector | String | Overrides the container the toolbars are kept inside. Defaults to the text field itself. |
| 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>
);
}
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. |
| scope | String | "instance" (the default) keeps one value per placement of the slide. "deck" shares one value with every slide and placement using this id. |
| 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. |
| isScrollable | Boolean | Scrolls content that overflows the field instead of clipping it. See Scrolling. |
| maskSelector | String | Overrides the container the toolbars are kept inside. Defaults to the text field itself. |
| disableSpellcheck | Boolean | Disables browser spellcheck. Defaults to false. |
| children | Node | Rendered to an HTML string and used as the default value. |
Scrolling​
A field clips content that overflows its box. Pass isScrollable to have it scroll that overflow instead.
The field needs a height to overflow. isScrollable only does something once the field has a definite height from
somewhere — a fixed height, or height: 100% inside a parent that constrains it. A field sized to its content never
overflows and so never scrolls.
className is applied to the field element itself, so that is where the height goes:
<ManagedTextField id="body_text" isCompany={true} className={style.field} isScrollable>
<p>Default text content.</p>
</ManagedTextField>
.field {
// Gives the field something to overflow. Without a height it grows with its
// content and `isScrollable` does nothing.
height: 240px;
}
height: 100% works in place of a fixed height wherever the parent constrains it — to fill what's left of a flex
column, give that parent flex: 1 1 auto; min-height: 0, the min-height: 0 being what lets it shrink below its
content.
Don't put the overflow on a wrapper instead. The toolbars resolve both their anchor clipping and their scroll
listener against the field element itself; adding a scrolling wrapper will break the toolbar tracking, allowing them to
drift out of position as you scroll. A wrapper with overflow: hidden is still fine for clipping a border radius around
the field.
Screenshots always clip, never scroll, isScrollable or not: a scrollbar in a rendered PDF would cut content
silently, and capturing a scrollable area needs the explicit multi-page screenshot configuration described in
Preso modes.
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" },
];
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"];
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,
},
];
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" ... />
Text format switching (ie. block types) is only available when the editable tag is a div.