Image Align Button

Available in Start plan

A fully accessible image alignment button for Tiptap editors. Control image positioning with left, center, and right alignment options, complete with keyboard shortcuts and smart image detection.

Installation

Add the component via the Tiptap CLI:

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

Components

`<ImageAlignButton />`

A prebuilt React component that controls image alignment in the editor.

Usage

export default function MyEditor() {
  return (
    <div>
      <ImageAlignButton
        editor={editor}
        align="left"
        text="Align Left"
        hideWhenUnavailable={true}
        showShortcut={true}
        onAligned={() => console.log('Image aligned!')}
      />
      <ImageAlignButton
        editor={editor}
        align="center"
        text="Align Center"
        hideWhenUnavailable={true}
        showShortcut={true}
      />
      <ImageAlignButton
        editor={editor}
        align="right"
        text="Align Right"
        hideWhenUnavailable={true}
        showShortcut={true}
      />
    </div>
  )
}

Props

Name	Type	Default	Description
`editor`	`Editor \| null`	`undefined`	The Tiptap editor instance
`align`	`'left' \| 'center' \| 'right'`	`undefined`	The alignment direction to apply
`text`	`string`	`undefined`	Optional text label for the button
`extensionName`	`string`	`'image'`	Name of the image extension to target
`attributeName`	`string`	`'data-align'`	Attribute name used for alignment
`hideWhenUnavailable`	`boolean`	`false`	Hides the button when alignment is not available
`onAligned`	`() => void`	`undefined`	Callback fired after a successful alignment change
`showShortcut`	`boolean`	`false`	Shows a keyboard shortcut badge

Hooks

`useImageAlign()`

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

Usage

function MyImageAlignButton({ align }: { align: 'left' | 'center' | 'right' }) {
  const { isVisible, handleImageAlign, canAlign, isActive, label, shortcutKeys, Icon } =
    useImageAlign({
      editor: myEditor,
      align,
      hideWhenUnavailable: true,
      onAligned: () => console.log(`Image aligned to ${align}!`),
    })

  if (!isVisible) return null

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

Props

Name	Type	Default	Description
`editor`	`Editor \| null`	`undefined`	The Tiptap editor instance
`align`	`'left' \| 'center' \| 'right'`	`undefined`	The alignment direction to apply
`extensionName`	`string`	`'image'`	Name of the image extension to target
`attributeName`	`string`	`'data-align'`	Attribute name used for alignment
`hideWhenUnavailable`	`boolean`	`false`	Hides the button when alignment is not available
`onAligned`	`() => void`	`undefined`	Callback fired after a successful alignment change

Return Values

Name	Type	Description
`isVisible`	`boolean`	Whether the button should be rendered
`canAlign`	`boolean`	If image alignment can be applied for the current node
`isActive`	`boolean`	If the current alignment is active
`handleImageAlign`	`() => boolean`	Function to apply the image alignment
`label`	`string`	Accessible label text for the button
`shortcutKeys`	`string`	Keyboard shortcut for this alignment
`Icon`	`React.FC`	Icon component for the alignment button

Utilities

`canSetImageAlign(editor, align, extensionName, attributeName)`

Checks if image alignment can be performed in the current editor state.

import { canSetImageAlign } from '@/components/tiptap-ui/image-align-button'

const canAlign = canSetImageAlign(editor, 'center', 'image', 'data-align')

`isImageAlignActive(editor, align, extensionName, attributeName)`

Checks if the specified image alignment is currently active.

import { isImageAlignActive } from '@/components/tiptap-ui/image-align-button'

const isActive = isImageAlignActive(editor, 'left', 'image', 'data-align')

`setImageAlign(editor, align, extensionName, attributeName)`

Programmatically sets the image alignment in the editor.

import { setImageAlign } from '@/components/tiptap-ui/image-align-button'

const success = setImageAlign(editor, 'right', 'image', 'data-align')
if (success) {
  console.log('Image alignment applied successfully!')
}

`shouldShowButton(props)`

Utility to determine if the image alignment button should be visible based on editor state and configuration.

import { shouldShowButton } from '@/components/tiptap-ui/image-align-button'

const shouldShow = shouldShowButton({
  editor,
  align: 'center',
  hideWhenUnavailable: true,
  extensionName: 'image',
  attributeName: 'data-align',
})

`<ImageAlignShortcutBadge />`

A helper component for displaying keyboard shortcuts in custom buttons.

import { ImageAlignShortcutBadge } from '@/components/tiptap-ui/image-align-button'
;<ImageAlignShortcutBadge align="center" />

Keyboard Shortcuts

The image alignment buttons support the following keyboard shortcuts:

Alt + Shift + L: Align image left
Alt + Shift + E: Align image center
Alt + Shift + R: Align image right

The shortcuts are automatically registered when using either the <ImageAlignButton /> component or the useImageAlign() hook. These shortcuts work when an image node is selected in the editor.

Alignment Options

Left Alignment

Aligns the image to the left side of the content area.

<ImageAlignButton editor={editor} align="left" />

Center Alignment

Centers the image horizontally within the content area.

<ImageAlignButton editor={editor} align="center" />

Right Alignment

Aligns the image to the right side of the content area.

<ImageAlignButton editor={editor} align="right" />

How It Works

The image alignment functionality works by:

Node Detection: Automatically detects when an image node is selected in the editor
Attribute Management: Updates the specified attribute (default: data-align) on the image node
State Tracking: Monitors the current alignment state and updates button active states
Accessibility: Provides proper ARIA labels and keyboard shortcuts for each alignment option
Extension Integration: Works with any Tiptap image extension that supports custom attributes

The alignment is applied by updating the image node's attributes, which can then be styled with CSS:

img[data-align='left'] {
  text-align: left;
}

img[data-align='center'] {
  text-align: center;
}

img[data-align='right'] {
  text-align: right;
}

Custom Extension Support

The component supports custom image extensions by allowing you to specify the extension name:

<ImageAlignButton
  editor={editor}
  align="center"
  extensionName="myCustomImage"
  attributeName="alignment"
/>

This flexibility allows you to use the alignment buttons with:

Custom image extensions
Extended image nodes with additional functionality
Different attribute naming conventions

Requirements

Dependencies

@tiptap/react - Core Tiptap React integration
react-hotkeys-hook - Keyboard shortcut management

Referenced Components

use-tiptap-editor (hook)
use-mobile (hook)
button (primitive)
badge (primitive)
tiptap-utils (lib)
align-center-vertical-icon (icon)
align-start-vertical-icon (icon)
align-end-vertical-icon (icon)

Extensions Required

This component works with any Tiptap image extension that supports custom attributes. The most common setup uses:

@tiptap/extension-image - Standard Tiptap image extension
Custom image extensions with attribute support

The extension should be configured to accept the alignment attribute:

import { Image } from '@tiptap/extension-image'

const editor = useEditor({
  extensions: [
    Image.configure({
      HTMLAttributes: {
        class: 'editor-image',
      },
    }),
  ],
})