MUI Components
NPM

MUITipTapRte

MUITipTapRte wraps Tiptap's headless useEditor hook, backed by an HTML string value — a lighter, dependency-thinner alternative to MUIRichTextEditor (CKEditor 5). Since Tiptap ships no UI of its own, this component includes a hand-built formatting toolbar (bold, italic, underline, strikethrough, headings, lists, blockquote, code block, links, alignment, undo/redo) driven entirely by the editor's own extensions.

Usage

import MUITipTapRte, {
  DefaultEditorExtensions,
  type MUITipTapRteProps
} from '@nish1896/mui-components/misc/tiptap-rte';

The value of bio will be an HTML string.

const [bio, setBio] = useState('');

<MUITipTapRte
  fieldName="bio"
  value={bio}
  onValueChange={({ newValue, editor }) => setBio(newValue)}
  placeholder="Tell us about yourself"
/>

onValueChange receives { newValue, editor }: the HTML string and the Tiptap Editor instance, so you can read other formats such as editor.getJSON().

Choosing the formatting options

Pass a custom editorExtensions array, or extend DefaultEditorExtensions, to control what the editor supports. Every toolbar button checks whether its backing extension is loaded before rendering. A custom set missing e.g. Heading or TextAlign simply omits those buttons instead of throwing an error when clicked.

import MUITipTapRte, { DefaultEditorExtensions } from '@nish1896/mui-components/misc/tiptap-rte';
import Table from '@tiptap/extension-table';

<MUITipTapRte
  fieldName="bio"
  value={bio}
  onValueChange={({ newValue }) => setBio(newValue)}
  editorExtensions={[...DefaultEditorExtensions, Table]}
/>

Configuring the editor

Use editorOptions to reach into useEditor for anything not exposed as its own prop. Pass onCreate, onFocus, onUpdate or onBlur here and they reach useEditor unmodified.

<MUITipTapRte
  fieldName="bio"
  value={bio}
  onValueChange={({ newValue }) => setBio(newValue)}
  editorOptions={{
    autofocus: true,
    onCreate: ({ editor }) => console.log('ready', editor),
    onFocus: ({ editor }) => console.log('focused', editor),
    onBlur: ({ editor }) => console.log('blurred', editor),
    onUpdate: ({ editor }) => console.log('newContent', editor.getHTML()),
    editorProps: { attributes: { spellcheck: 'false' } }
  }}
/>
  • onUpdate is never replaced, only chained. It first calls onValueChange with the editor's latest HTML, then your editorOptions.onUpdate, so value is always in sync by the time your own handler runs.
  • editorOptions is layered underneath this component's own required wiring (content, editable and the accessibility attributes), so it can't break the controlled-value contract.
  • editorProps.attributes is deep-merged rather than replaced.

Styling the editor

containerProps styles the outer bordered box, and contentContainerProps styles the scrollable box directly wrapping the editor content. Both merge their sx with this component's own base styles rather than replacing them.

<MUITipTapRte
  fieldName="bio"
  value={bio}
  onValueChange={({ newValue }) => setBio(newValue)}
  containerProps={{ sx: { borderColor: 'primary.main' } }}
  contentContainerProps={{ sx: { minHeight: 240 } }}
/>

Custom toolbar

renderToolbar replaces the built-in toolbar entirely. Pass () => null to hide it. It receives the live editor instance and the field's resolved disabled state, so a custom toolbar can drive the same editor.chain()...run() commands and respect the same disabled state.

<MUITipTapRte
  fieldName="bio"
  value={bio}
  onValueChange={({ newValue }) => setBio(newValue)}
  renderToolbar={(editor, disabled) => (
    <Button
      disabled={disabled}
      onClick={() => editor.chain().focus().toggleBold().run()}
    >
      Bold
    </Button>
  )}
/>

API

Pass a custom editorExtensions to control the Tiptap extension set (and, in turn, which toolbar buttons render). Props marked with * are required.

NameTypeDescription
fieldName*string
Name/path of the field. Used to derive generated ids and the default label.
valuestring | null
Current editor HTML string.
onValueChange*({ newValue, editor }) => void
Called when the editor content changes, with the updated HTML string and editor instance.
editorOptionsUseEditorOptions
Additional options passed straight through to the useEditor hook — e.g. onCreate, onFocus, onBlur, autofocus, editorProps.handleDOMEvents, parseOptions, injectCSS. editorProps.attributes is deep-merged instead of replaced.
onUpdate is also passed through, but this component's own onUpdate (which calls onValueChange) always runs first.
editorExtensionsAnyExtension[]
Tiptap extensions passed to useEditor. Defaults to this package's DefaultEditorExtensions. The built-in toolbar omits any button whose backing extension isn't loaded, so a custom set missing e.g. Heading or TextAlign simply hides those controls instead of throwing when clicked.
containerPropsBoxProps
Props forwarded to the outer bordered container wrapping the toolbar and editor content. containerProps.sx is merged with the component's own base styles (border, radius, focus ring) rather than replacing them, and accepts any sx form — object, array, or function.
contentContainerPropsBoxProps
Props forwarded to the scrollable Box directly wrapping EditorContent (padding, min/max height, and the .ProseMirror/placeholder styling). contentContainerProps.sx is merged the same way as containerProps.sx.
renderToolbar(editor: Editor, disabled: boolean) => ReactNode
Custom toolbar renderer, called with the live editor instance and the field's resolved disabled state. Defaults to this package's built-in Toolbar. Pass () => null to hide the toolbar entirely.
requiredboolean
Indicates that the field is mandatory by adding an asterisk symbol (*) to the form label and setting the relevant accessibility attributes.
placeholderstring
Placeholder text shown when the editor is empty. Always applied via an internal Placeholder extension appended after editorExtensions (or DefaultEditorExtensions), regardless of which set is active.
disabledboolean
When true, disables the field and associated controls.
labelReactNode
Label displayed for the field. Defaults to a human-readable label derived from fieldName, e.g. firstName becomes "First Name".
showLabelAboveFormFieldboolean
Whether the field label renders above the component. Since it has no built-in inline label, the label renders above the component by default; pass false to hide the visible label (the accessible name is still applied). Takes precedence over allLabelsAboveFields from the ConfigProvider.
Default: true
hideLabelboolean
When true, hides the rendered field label while preserving accessible labeling where possible.
formLabelPropsFormLabelProps
FormLabelProps forwarded to the internal FormLabel. The id is managed by the component. Multiple fields can be configured using the ConfigProvider component.
errorMessagestring | string[]
Validation error for the field — pass a single message string, or a string[] when the field can fail multiple rules at once (every message is shown together). A non-empty string or array puts the field in an error state; undefined/''/[] clear it.
Normalize your form library's error shape to this at the call site (e.g. an RHF FieldError via its .message). Use renderError to customize how the message(s) are rendered.
renderError(errors: string[]) => ReactNode
Custom renderer for the resolved error message(s), called only when the field is in an error state. Always receives a string[] — use errors[0] for the common single-message case, or map over errors when a field fails several rules. By default a single message renders as text and multiple messages render on separate lines.
hideErrorMessageboolean
If true, hides the error message text while keeping the field in an error state.
helperTextReactNode
Content displayed in the FormHelperText component below the field when there is no visible validation error.
formHelperTextPropsFormHelperTextProps
FormHelperTextProps forwarded to the internal FormHelperText. The id is managed by the component. Multiple fields can be configured using the ConfigProvider component.
customIds{ field, label, helperText, error }
Overrides the default field, label, helper text, and error IDs used for accessibility.

Playground

Driven by plain React state — the value is an HTML string; a required editor with a custom label and validation, plus one with the label above the field.

Required editor with a custom label & validation

Editor with the label above the field & helperText

Optional — anything else we should know?

Custom extensions, toolbar, markdown & style overrides

Value above stays an HTML string — this preview reads editor.storage.markdown.getMarkdown() (from the Markdown extension) via editorOptions.onCreate/onUpdate.

Form State - Values & Errors

Source Code

View the full implementation of this component on GitHub.