Placeholder

Show some placeholder text when the current text block is empty or the whole document is empty.

editor.tsx
extension.ts

import 'prosekit/basic/style.css'
import 'prosekit/basic/typography.css'

import {
  createEditor,
  jsonFromNode,
  type NodeJSON,
} from 'prosekit/core'
import type { ProseMirrorNode } from 'prosekit/pm/model'
import {
  ProseKit,
  useDocChange,
} from 'prosekit/react'
import {
  useCallback,
  useMemo,
} from 'react'

import { defineExtension } from './extension'

export default function Editor({
  defaultContent,
  onDocUpdate,
}: {
  defaultContent?: NodeJSON
  onDocUpdate?: (doc: NodeJSON) => void
}) {
  const editor = useMemo(() => {
    const extension = defineExtension()
    return createEditor({ extension, defaultContent })
  }, [defaultContent])

  const handleDocChange = useCallback(
    (doc: ProseMirrorNode) => onDocUpdate?.(jsonFromNode(doc)),
    [onDocUpdate],
  )
  useDocChange(handleDocChange, { editor })

  return (
    <ProseKit editor={editor}>
      <div className="box-border h-full w-full min-h-36 overflow-y-hidden overflow-x-hidden rounded-md border border-solid border-gray-200 dark:border-gray-700 shadow flex flex-col bg-white dark:bg-gray-950 color-black dark:color-white">
        <div className="relative w-full flex-1 box-border overflow-y-scroll">
          <div ref={editor.mount} className="ProseMirror box-border min-h-full px-[max(4rem,_calc(50%-20rem))] py-8 outline-none outline-0 [&_span[data-mention=user]]:text-blue-500 [&_span[data-mention=tag]]:text-violet-500"></div>
        </div>
      </div>
    </ProseKit>
  )
}

import { defineBasicExtension } from 'prosekit/basic'
import { union } from 'prosekit/core'
import { definePlaceholder } from 'prosekit/extensions/placeholder'

export function defineExtension() {
  return union(
    defineBasicExtension(),
    definePlaceholder({ placeholder: 'Type something...' }),
  )
}

export type EditorExtension = ReturnType<typeof defineExtension>

editor.vue
extension.ts

<script setup lang="ts">
import 'prosekit/basic/style.css'
import 'prosekit/basic/typography.css'

import { createEditor } from 'prosekit/core'
import { ProseKit } from 'prosekit/vue'
import {
  ref,
  watchPostEffect,
} from 'vue'

import { defineExtension } from './extension'

const editor = createEditor({ extension: defineExtension() })

const editorRef = ref<HTMLDivElement | null>(null)
watchPostEffect((onCleanup) => {
  editor.mount(editorRef.value)
  onCleanup(() => editor.unmount())
})
</script>

<template>
  <ProseKit :editor="editor">
    <div class="box-border h-full w-full min-h-36 overflow-y-hidden overflow-x-hidden rounded-md border border-solid border-gray-200 dark:border-gray-700 shadow flex flex-col bg-white dark:bg-gray-950 color-black dark:color-white">
      <div class="relative w-full flex-1 box-border overflow-y-scroll">
        <div
          ref="editorRef"
          spellcheck="false"
          class="ProseMirror box-border min-h-full px-[max(4rem,_calc(50%-20rem))] py-8 outline-none outline-0 [&_span[data-mention=user]]:text-blue-500 [&_span[data-mention=tag]]:text-violet-500"
        />
      </div>
    </div>
  </ProseKit>
</template>

import { defineBasicExtension } from 'prosekit/basic'
import { union } from 'prosekit/core'
import { definePlaceholder } from 'prosekit/extensions/placeholder'

export function defineExtension() {
  return union(
    defineBasicExtension(),
    definePlaceholder({ placeholder: 'Type something...' }),
  )
}

export type EditorExtension = ReturnType<typeof defineExtension>

Usage

import { definePlaceholderfunction definePlaceholder(options: PlaceholderOptions): PlainExtensionAdd a placeholder text to the editor when the current block or document is
empty. } from 'prosekit/extensions/placeholder'

const extensionconst extension: PlainExtension = definePlaceholderfunction definePlaceholder(options: PlaceholderOptions): PlainExtensionAdd a placeholder text to the editor when the current block or document is
empty.({ placeholderPlaceholderOptions.placeholder: string | ((state: EditorState) => string)The placeholder to use. It can be a static string or a function that
receives the current editor state and returns a string.: 'Type Something...' })

You can also show dynamic placeholders based on the current state.

import type { HeadingAttrs } from 'prosekit/extensions/heading'
import { definePlaceholderfunction definePlaceholder(options: PlaceholderOptions): PlainExtensionAdd a placeholder text to the editor when the current block or document is
empty. } from 'prosekit/extensions/placeholder'

const extensionconst extension: PlainExtension = definePlaceholderfunction definePlaceholder(options: PlaceholderOptions): PlainExtensionAdd a placeholder text to the editor when the current block or document is
empty.({
  placeholderPlaceholderOptions.placeholder: string | ((state: EditorState) => string)The placeholder to use. It can be a static string or a function that
receives the current editor state and returns a string.: (statestate: EditorState) => {
    // Get the current node at the text selection
    const nodeconst node: Node = statestate: EditorState.selectionEditorState.selection: SelectionThe selection..$fromSelection.$from: ResolvedPosThe resolved lower  bound of the selection's main range..nodeResolvedPos.node(depth?: number | null): NodeThe ancestor node at the given level. `p.node(p.depth)` is the
same as `p.parent`.()
    // Show different placeholders based on the node type
    if (nodeconst node: Node.typeNode.type: NodeTypeThe type of node that this is..nameNodeType.name: stringThe name the node type has in this schema. === 'heading') {
      const attrsconst attrs: HeadingAttrs = nodeconst node: Node.attrsNode.attrs: AttrsAn object mapping attribute names to values. The kind of
attributes allowed and required are
[determined](https://prosemirror.net/docs/ref/#model.NodeSpec.attrs) by the node type. as HeadingAttrs
      return `Heading ${attrsconst attrs: HeadingAttrs.levelHeadingAttrs.level: number}`
    }
    return 'Type something...'
  },
})

Note that you would need to import the style file for the extension to work.

API Reference

prosekit/extensions/placeholder