Find out what's new in Tiptap Editor 3.0

Text align button

Available for free

A fully accessible text align button for Tiptap editors. Easily set text alignment to left, center, right, or justify with keyboard shortcut support and flexible customization options.

Installation

Add the component via the Tiptap CLI:

npx @tiptap/cli@latest add text-align-button

Components

<TextAlignButton />

A prebuilt React component that sets text alignment for a specific alignment type.

Usage

import { EditorContent, EditorContext, useEditor } from '@tiptap/react'
import { StarterKit } from '@tiptap/starter-kit'
import { TextAlign } from '@tiptap/extension-text-align'
import { TextAlignButton } from '@/components/tiptap-ui/text-align-button'

import '@/components/tiptap-node/paragraph-node/paragraph-node.scss'

export default function MyEditor() {
  const editor = useEditor({
    immediatelyRender: false,
    extensions: [StarterKit, TextAlign.configure({ types: ['heading', 'paragraph'] })],
    content: `
        <p>Try selecting a paragraph and clicking one of the text alignment buttons.</p>
        <p style="text-align: left">Left-aligned text.</p>
        <p style="text-align: center">Center-aligned text.</p>
        <p style="text-align: right">Right-aligned text.</p>
        <p style="text-align: justify">Justified text.</p>
        `,
  })

  return (
    <EditorContext.Provider value={{ editor }}>
      <TextAlignButton
        editor={editor}
        align="left"
        text="Left"
        hideWhenUnavailable={true}
        showShortcut={true}
        onAligned={() => console.log('Text aligned!')}
      />
      <TextAlignButton align="center" />
      <TextAlignButton align="right" />
      <TextAlignButton align="justify" />

      <EditorContent editor={editor} role="presentation" />
    </EditorContext.Provider>
  )
}

Props

NameTypeDefaultDescription
editorEditor | nullundefinedThe Tiptap editor instance
alignTextAlignrequiredThe alignment type ("left", "center", "right", "justify")
textstringundefinedOptional text label for the button
hideWhenUnavailablebooleanfalseHides the button when alignment is not available
onAligned() => voidundefinedCallback fired after a successful alignment change
showShortcutbooleanfalseShows a keyboard shortcut badge (if available)

Hooks

useTextAlign()

A custom hook to build your own text align button with full control over rendering and behavior.

Usage

function MyTextAlignButton() {
  const { isVisible, isActive, canAlign, handleTextAlign, label, shortcutKeys, Icon } =
    useTextAlign({
      editor: myEditor,
      align: 'center',
      hideWhenUnavailable: true,
      onAligned: () => console.log('Text aligned!'),
    })

  if (!isVisible) return null

  return (
    <button
      onClick={handleTextAlign}
      disabled={!canAlign}
      aria-label={label}
      aria-pressed={isActive}
    >
      <Icon />
      {label}
      {shortcutKeys && <Badge>{parseShortcutKeys({ shortcutKeys })}</Badge>}
    </button>
  )
}

Props

NameTypeDefaultDescription
editorEditor | nullundefinedThe Tiptap editor instance
alignTextAlignrequiredThe alignment type to apply
hideWhenUnavailablebooleanfalseHides the button if alignment is not available
onAligned() => voidundefinedCallback fired after a successful alignment change

Return Values

NameTypeDescription
isVisiblebooleanWhether the button should be rendered
isActivebooleanIf the specific alignment is currently active
canAlignbooleanIf text alignment is currently allowed
handleTextAlign() => booleanFunction to set text alignment
labelstringAccessible label text for the button
shortcutKeysstringKeyboard shortcut for the specific alignment
IconReact.FCIcon component for the text align button

Utilities

canSetTextAlign(editor, align)

Checks if a specific text alignment can be set in the current editor state.

import { canSetTextAlign } from '@/components/tiptap-ui/text-align-button'

const canAlign = canSetTextAlign(editor, 'center') // Check if center alignment can be set

setTextAlign(editor, align)

Programmatically sets text alignment for the specified type.

import { setTextAlign } from '@/components/tiptap-ui/text-align-button'

const success = setTextAlign(editor, 'right')
if (success) {
  console.log('Text aligned to right successfully!')
}

isTextAlignActive(editor, align)

Checks if a specific text alignment is currently active.

import { isTextAlignActive } from '@/components/tiptap-ui/text-align-button'

const active = isTextAlignActive(editor, 'justify')

Keyboard Shortcuts

Each alignment type has its own keyboard shortcut:

  • Cmd/Ctrl + Shift + L: Align left
  • Cmd/Ctrl + Shift + E: Align center
  • Cmd/Ctrl + Shift + R: Align right
  • Cmd/Ctrl + Shift + J: Align justify

The shortcuts are automatically registered when using either the <TextAlignButton /> component or the useTextAlign() hook.

Requirements

Dependencies

  • @tiptap/react - Core Tiptap React integration
  • @tiptap/extension-text-align - Text alignment extension
  • react-hotkeys-hook - Keyboard shortcut management

Referenced Components

  • use-tiptap-editor (hook)
  • button (primitive)
  • badge (primitive)
  • tiptap-utils (lib)
  • align-left-icon (icon)
  • align-center-icon (icon)
  • align-right-icon (icon)
  • align-justify-icon (icon)
close