---
title: "Image Align Button"
description: "Align images in your Tiptap editor with left, center, and right alignment controls, keyboard shortcuts, and accessibility support."
canonical_url: "https://tiptap.dev/docs/ui-components/components/image-align-button"
---

# Image Align Button

Align images in your Tiptap editor with left, center, and right alignment controls, keyboard shortcuts, and accessibility support.

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.

> **Interactive demo:** [image align button](https://template.tiptap.dev/preview/tiptap-ui/image-align-button)

## Installation

Add the component via the Tiptap CLI:

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

## Components

### `<ImageAlignButton />`

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

#### Usage

```tsx
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

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

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

### Center Alignment

Centers the image horizontally within the content area.

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

### Right Alignment

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

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

## How It Works

The image alignment functionality works by:

1. **Node Detection**: Automatically detects when an image node is selected in the editor
2. **Attribute Management**: Updates the specified attribute (default: `data-align`) on the image node
3. **State Tracking**: Monitors the current alignment state and updates button active states
4. **Accessibility**: Provides proper ARIA labels and keyboard shortcuts for each alignment option
5. **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:

```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:

```tsx
<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:

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

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