Placeholder
Show placeholder text in empty blocks with a string, a function of the block or the bundled Notion placeholders, and style it through the data-placeholder attribute.
A placeholder is hint text shown in an empty block, such as “Type ‘/’ for commands”. It is never part of the document: the editor renders it with CSS from a data-placeholder attribute.
Setting a placeholder
A placeholder is a plugin’s: return placeholder from a plugin you list.
<script lang="ts">
import { Edytor } from 'edytor';
</script>
<Edytor plugins={[() => ({ placeholder: 'Start writing…' })]} />
A string shows in every empty block. A function decides per block:
import type { Plugin } from 'edytor';
export const hintsPlugin: Plugin = () => ({
placeholder: ({ type, data, focused }) => {
if (type === 'heading') return `Heading ${String(data.level ?? 'h1').slice(1)}`;
if (type === 'todo-item') return 'To-do';
return focused ? "Type '/' for commands" : null;
}
});
The function receives a view of the empty block and returns the text, or null for none:
type?string
The block's kind.
stringdata?object
The block's data.
objectfocused?boolean
The caret is in the block.
booleanempty?boolean
Always true: the function is only asked for empty blocks.
booleanThe function re-runs when the block’s kind, data or focus changes, so a placeholder can follow the caret. The plugin list itself is read once, when the editor mounts. Among plugins, the first one that declares a placeholder wins.
Notion placeholders
richTextPlaceholder is a ready-made function with Notion’s hints for the rich text and image kinds:
<script lang="ts">
import { Edytor, richTextPlaceholder } from 'edytor';
</script>
<Edytor plugins={[() => ({ placeholder: richTextPlaceholder })]} />
| Kind | Placeholder |
|---|---|
heading |
“Heading 1”, “Heading 2” or “Heading 3” |
toggle-heading |
“Toggle heading 1”, “Toggle heading 2” or “Toggle heading 3” |
bulleted-list-item, numbered-list-item |
“List” |
todo-item |
“To-do” |
toggle |
“Toggle” |
quote |
“Empty quote” |
callout (its title) |
“Callout title” |
image, embed, bookmark, file, video, audio (the caption) |
“Write a caption…”, only while focused |
any other kind, such as paragraph |
“Type ‘/’ for commands”, only while focused |
Its words are the view’s richText labels’ placeholders (heading is a function of the level): <Edytor plugins={[() => ({ placeholder: richTextPlaceholder })]} labels={{ richText: { placeholders: { quote: 'Citation vide' } } }} />. See Localization. A placeholder function receives the empty block’s values and the view; to change one case, wrap it: placeholder: (view, edytor) => (view.type === 'quote' ? 'Quote' : richTextPlaceholder(view, edytor)).
When it shows
A block shows its placeholder when its content is a single empty text: no characters and no inline atoms. Its children do not count. It is withheld while an IME composition is in progress in the block, so the hint never overlaps composed text. Kinds that render no content (list containers, dividers) never show one.
Styling
The placeholder is an attribute on the empty text element:
<span data-edytor-text="true" data-placeholder="Start writing…"></span>
The editor ships one rule that draws it:
[data-edytor-text][data-placeholder]::before {
content: attr(data-placeholder);
position: absolute;
white-space: nowrap;
pointer-events: none;
user-select: none;
opacity: 0.45;
}
It is positioned out of flow, so the caret stays at the start of the line and clicks go to the text. Override the look with your own rule:
[data-edytor] [data-placeholder]::before {
color: #b6b4af;
opacity: 1;
font-style: italic;
}
To style by kind, go through the block element and the element holding its own text: [data-edytor-type='heading'] > :is(h1, h2, h3) > [data-placeholder]::before. A bare descendant selector ([data-edytor-type='heading'] [data-placeholder]) also reaches the placeholders of the blocks nested in it.