placeholder.mdx

title	Placeholder extension
tags	type src url label image https://img.shields.io/npm/v/@tiptap/extensions?label=version https://www.npmjs.com/package/@tiptap/extensions Version type src url label image https://img.shields.io/npm/dm/@tiptap/extensions.svg https://npmcharts.com/compare/@tiptap/extensions?minimal=true Downloads
meta	title description category Placeholder extension | Tiptap Editor Docs Configure a helpful placeholder to fill the emptiness in your Tiptap editor. Learn how to set up and use it here in the Docs! Editor
extension	name link description type icon Placeholder https://github.com/ueberdosis/tiptap/tree/main/packages/extensions Configure a helpful placeholder to fill the emptiness. extension Ghost

import { CodeDemo } from '@/components/CodeDemo'

This extension provides placeholder support. Give your users an idea what they should write with a tiny hint. There is a handful of things to customize, if you feel like it.

Install

npm install @tiptap/extensions

Usage

import { Editor } from '@tiptap/core'
import { Placeholder } from '@tiptap/extensions'

new Editor({
  extensions: [
    Placeholder.configure({
      placeholder: 'Write something …',
    }),
  ],
})

Additional Setup

Placeholders are displayed with the help of CSS.

Display a Placeholder only for the first line in an empty editor.

.tiptap p.is-editor-empty:first-child::before {
  color: #adb5bd;
  content: attr(data-placeholder);
  float: left;
  height: 0;
  pointer-events: none;
}

Display Placeholders on every new line.

.tiptap p.is-empty::before {
  color: #adb5bd;
  content: attr(data-placeholder);
  float: left;
  height: 0;
  pointer-events: none;
}

Settings

emptyEditorClass

The added CSS class if the editor is empty.

Default: 'is-editor-empty'

Placeholder.configure({
  emptyEditorClass: 'is-editor-empty',
})

emptyNodeClass

The added CSS class if the node is empty.

Default: 'is-empty'

Placeholder.configure({
  emptyNodeClass: 'my-custom-is-empty-class',
})

dataAttribute

The data attribute used to store the placeholder text. When setting this to 'my-placeholder', the placeholder text will be stored in the data-my-placeholder attribute, for example.

Default: 'placeholder'

Placeholder.configure({
  dataAttribute: 'my-placeholder'
})

placeholder

The placeholder text added as data-placeholder attribute.

Default: 'Write something …'

Placeholder.configure({
  placeholder: 'My Custom Placeholder',
})

You can even use a function to add placeholder depending on the node:

Placeholder.configure({
  placeholder: ({ node }) => {
    if (node.type.name === 'heading') {
      return 'What’s the title?'
    }

    return 'Can you add some further context?'
  },
})

showOnlyWhenEditable

Show decorations only when editor is editable.

Default: true

Placeholder.configure({
  showOnlyWhenEditable: false,
})

showOnlyCurrent

Show decorations only in currently selected node.

Default: true

Placeholder.configure({
  showOnlyCurrent: false,
})

includeChildren

Show decorations also for nested nodes.

Default: false

Placeholder.configure({
  includeChildren: true,
})

excludedNodeTypes

Exclude specific node types from showing placeholders. This is useful when using includeChildren: true to prevent placeholders from appearing on wrapper nodes (like lists) while still showing them on actual content nodes.

Default: []

Placeholder.configure({
  includeChildren: true,
  excludedNodeTypes: ['bulletList', 'orderedList', 'listItem'],
})

Source code

packages/extensions/src/placeholder

Minimal Install

import { Editor } from '@tiptap/core'
import { Placeholder } from '@tiptap/extensions/placeholder'

new Editor({
  extensions: [Placeholder],
})