v2.1.16
/
Use our Nuxt starter

EditorToolbar

A customizable toolbar for editor actions with multiple display modes: fixed, bubble, or floating.
GitHub
Demo
Nuxt UI

Usage

The EditorToolbar component displays a toolbar of formatting buttons that automatically sync their active state with the editor content. It supports three layout modes using the @tiptap/vue-3/menus package:

  • fixed (always visible)
  • bubble (appears on text selection)
  • floating (appears on empty lines)
It must be used inside an Editor component's default slot to have access to the editor instance.
<script setup lang="ts">
import type { EditorToolbarItem } from '@bitrix24/b24ui-nuxt'
import HeaderIcon from '@bitrix24/b24icons-vue/editor/HeaderIcon'
import BoldIcon from '@bitrix24/b24icons-vue/outline/BoldIcon'
import ItalicIcon from '@bitrix24/b24icons-vue/outline/ItalicIcon'
import UnderlineIcon from '@bitrix24/b24icons-vue/outline/UnderlineIcon'
import StrikethroughIcon from '@bitrix24/b24icons-vue/outline/StrikethroughIcon'
import DeveloperResourcesIcon from '@bitrix24/b24icons-vue/outline/DeveloperResourcesIcon'

const value = ref(`# Toolbar

Select some text to see the formatting toolbar appear above your selection.`)

const items: EditorToolbarItem[][] = [
  [
    {
      icon: HeaderIcon,
      tooltip: { text: 'Headings' },
      content: { align: 'start' },
      items: [
        {
          kind: 'heading',
          level: 1,
          label: 'Heading 1'
        },
        {
          kind: 'heading',
          level: 2,
          label: 'Heading 2'
        },
        {
          kind: 'heading',
          level: 3,
          label: 'Heading 3'
        },
        {
          kind: 'heading',
          level: 4,
          label: 'Heading 4'
        }
      ]
    }
  ],
  [
    {
      kind: 'mark',
      mark: 'bold',
      icon: BoldIcon,
      tooltip: { text: 'Bold' }
    },
    {
      kind: 'mark',
      mark: 'italic',
      icon: ItalicIcon,
      tooltip: { text: 'Italic' }
    },
    {
      kind: 'mark',
      mark: 'underline',
      icon: UnderlineIcon,
      tooltip: { text: 'Underline' }
    },
    {
      kind: 'mark',
      mark: 'strike',
      icon: StrikethroughIcon,
      tooltip: { text: 'Strikethrough' }
    },
    {
      kind: 'mark',
      mark: 'code',
      icon: DeveloperResourcesIcon,
      tooltip: { text: 'Code' }
    }
  ]
]
</script>

<template>
  <B24Editor v-slot="{ editor }" v-model="value" content-type="markdown" class="w-full min-h-21">
    <B24EditorToolbar :editor="editor" :items="items" layout="bubble" />
  </B24Editor>
</template>
The bubble and floating layouts use TipTap's BubbleMenu and FloatingMenu extensions.

Items

Use the items prop as an array of objects with the following properties:

You can pass any property from the Button component such as color, size, etc.

<script setup lang="ts">
import type { EditorToolbarItem } from '@bitrix24/b24ui-nuxt'
import { TextAlign } from '@tiptap/extension-text-align'
import UndoIcon from '@bitrix24/b24icons-vue/outline/UndoIcon'
import RedoIcon from '@bitrix24/b24icons-vue/outline/RedoIcon'
import HeaderIcon from '@bitrix24/b24icons-vue/editor/HeaderIcon'
import BulletedListIcon from '@bitrix24/b24icons-vue/outline/BulletedListIcon'
import NumberedListIcon from '@bitrix24/b24icons-vue/outline/NumberedListIcon'
import QuoteIcon from '@bitrix24/b24icons-vue/outline/QuoteIcon'
import CodeIcon from '@bitrix24/b24icons-vue/common-service/CodeIcon'
import HrIcon from '@bitrix24/b24icons-vue/editor/HrIcon'
import BoldIcon from '@bitrix24/b24icons-vue/outline/BoldIcon'
import ItalicIcon from '@bitrix24/b24icons-vue/outline/ItalicIcon'
import UnderlineIcon from '@bitrix24/b24icons-vue/outline/UnderlineIcon'
import StrikethroughIcon from '@bitrix24/b24icons-vue/outline/StrikethroughIcon'
import DeveloperResourcesIcon from '@bitrix24/b24icons-vue/outline/DeveloperResourcesIcon'
import LinkIcon from '@bitrix24/b24icons-vue/outline/LinkIcon'
import AlignLeftIcon from '@bitrix24/b24icons-vue/outline/AlignLeftIcon'
import AlignCenterIcon from '@bitrix24/b24icons-vue/outline/AlignCenterIcon'
import AlignRightIcon from '@bitrix24/b24icons-vue/outline/AlignRightIcon'
import AlignJustifyIcon from '@bitrix24/b24icons-vue/outline/AlignJustifyIcon'

const value = ref(`This toolbar showcases **all available formatting options** using built-in handlers. Try the different controls to see them in action!

You can apply **bold**, *italic*, <u>underline</u>, ~~strikethrough~~, and \`inline code\` formatting to your text.
`)

const items: EditorToolbarItem[][] = [
  // History controls
  [
    {
      kind: 'undo',
      icon: UndoIcon,
      tooltip: { text: 'Undo' }
    },
    {
      kind: 'redo',
      icon: RedoIcon,
      tooltip: { text: 'Redo' }
    }
  ],
  // Block types
  [
    {
      icon: HeaderIcon,
      tooltip: { text: 'Headings' },
      content: { align: 'start' },
      items: [
        {
          kind: 'heading',
          level: 1,
          label: 'Heading 1'
        },
        {
          kind: 'heading',
          level: 2,
          label: 'Heading 2'
        },
        {
          kind: 'heading',
          level: 3,
          label: 'Heading 3'
        },
        {
          kind: 'heading',
          level: 4,
          label: 'Heading 4'
        }
      ]
    },
    {
      icon: BulletedListIcon,
      tooltip: { text: 'Lists' },
      content: {
        align: 'start'
      },
      items: [
        {
          kind: 'bulletList',
          icon: BulletedListIcon,
          label: 'Bullet List'
        },
        {
          kind: 'orderedList',
          icon: NumberedListIcon,
          label: 'Ordered List'
        }
      ]
    },
    {
      kind: 'blockquote',
      icon: QuoteIcon,
      tooltip: { text: 'Blockquote' }
    },
    {
      kind: 'codeBlock',
      icon: CodeIcon,
      tooltip: { text: 'Code Block' }
    },
    {
      kind: 'horizontalRule',
      icon: HrIcon,
      tooltip: { text: 'Horizontal Rule' }
    }
  ],
  // Text formatting
  [
    {
      kind: 'mark',
      mark: 'bold',
      icon: BoldIcon,
      tooltip: { text: 'Bold' }
    },
    {
      kind: 'mark',
      mark: 'italic',
      icon: ItalicIcon,
      tooltip: { text: 'Italic' }
    },
    {
      kind: 'mark',
      mark: 'underline',
      icon: UnderlineIcon,
      tooltip: { text: 'Underline' }
    },
    {
      kind: 'mark',
      mark: 'strike',
      icon: StrikethroughIcon,
      tooltip: { text: 'Strikethrough' }
    },
    {
      kind: 'mark',
      mark: 'code',
      icon: DeveloperResourcesIcon,
      tooltip: { text: 'Code' }
    }
  ],
  // Link
  [
    {
      kind: 'link',
      icon: LinkIcon,
      tooltip: { text: 'Link' }
    }
  ],
  // Text alignment
  [
    {
      icon: AlignJustifyIcon,
      tooltip: { text: 'Text Align' },
      content: {
        align: 'end'
      },
      items: [
        {
          kind: 'textAlign',
          align: 'left',
          icon: AlignLeftIcon,
          label: 'Align Left'
        }, {
          kind: 'textAlign',
          align: 'center',
          icon: AlignCenterIcon,
          label: 'Align Center'
        }, {
          kind: 'textAlign',
          align: 'right',
          icon: AlignRightIcon,
          label: 'Align Right'
        }, {
          kind: 'textAlign',
          align: 'justify',
          icon: AlignJustifyIcon,
          label: 'Align Justify'
        }
      ]
    }
  ]
]
</script>

<template>
  <B24Editor
    v-slot="{ editor }"
    v-model="value"
    content-type="markdown"
    :extensions="[TextAlign.configure({ types: ['heading', 'paragraph'] })]"
    class="w-full min-h-37 flex flex-col gap-4"
  >
    <B24EditorToolbar :editor="editor" :items="items" class="sm:px-8 overflow-x-auto bg-(--ui-color-bg-content-primary)" />
  </B24Editor>
</template>
You can also pass an array of arrays to the items prop to create separated groups of items.
Each item can take an items array of objects with the same properties as the items prop to create a DropdownMenu.

Layout

Use the layout prop to change how the toolbar is displayed. Defaults to fixed.

<script setup lang="ts">
import type { EditorToolbarItem } from '@bitrix24/b24ui-nuxt'
import BoldIcon from '@bitrix24/b24icons-vue/outline/BoldIcon'
import ItalicIcon from '@bitrix24/b24icons-vue/outline/ItalicIcon'
import DeveloperResourcesIcon from '@bitrix24/b24icons-vue/outline/DeveloperResourcesIcon'

defineProps<{
  layout: 'fixed' | 'bubble' | 'floating'
}>()

const value = ref(`Switch between layouts to see the different toolbar modes.

The **fixed** layout displays the toolbar above the editor. The **bubble** layout shows the toolbar when you select text. The **floating** layout appears on empty lines.`)

const items: EditorToolbarItem[][] = [
  [
    {
      kind: 'mark',
      mark: 'bold',
      icon: BoldIcon
    },
    {
      kind: 'mark',
      mark: 'italic',
      icon: ItalicIcon
    },
    {
      kind: 'mark',
      mark: 'code',
      icon: DeveloperResourcesIcon
    }
  ]
]
</script>

<template>
  <B24Editor v-slot="{ editor }" v-model="value" content-type="markdown" class="w-full min-h-26 flex flex-col gap-4">
    <B24EditorToolbar
      :key="layout"
      :editor="editor"
      :items="items"
      :layout="layout"
      :data-layout="layout"
      class="data-[layout=fixed]:sm:px-8"
    />
  </B24Editor>
</template>

Options

When using bubble or floating layouts, use the options prop to customize the positioning behavior using Floating UI options.

<template>
  <B24Editor v-slot="{ editor }">
    <B24EditorToolbar
      :editor="editor"
      :items="items"
      layout="bubble"
      :options="{
        placement: 'top',
        offset: 8,
        flip: { padding: 8 },
        shift: { padding: 8 }
      }"
    />
  </B24Editor>
</template>

Should Show

When using bubble or floating layouts, use the should-show prop to control when the toolbar appears. This function receives context about the editor state and returns a boolean.

<template>
  <B24Editor v-slot="{ editor }">
    <B24EditorToolbar
      :editor="editor"
      :items="items"
      layout="bubble"
      :should-show="({ view, state }) => {
        const { selection } = state
        const { from, to } = selection
        const text = state.doc.textBetween(from, to)
        return view.hasFocus() && !selection.empty && text.length > 10
      }"
    />
  </B24Editor>
</template>

Examples

With image toolbar

Use the should-show prop to create context-specific toolbars that appear only for certain node types. This example shows a bubble toolbar with download and delete actions that only appears when an image is selected.

<script setup lang="ts">
import type { Editor } from '@tiptap/vue-3'
import type { EditorToolbarItem } from '@bitrix24/b24ui-nuxt'
import DownloadIcon from '@bitrix24/b24icons-vue/outline/DownloadIcon'
import TrashcanIcon from '@bitrix24/b24icons-vue/outline/TrashcanIcon'

const value = ref(`Click on the image below to see the image-specific toolbar:

![Placeholder](https://bitrix24.github.io/b24ui/assets/demo/b24rich_new.png)`)

const items = (editor: Editor): EditorToolbarItem[][] => {
  const node = editor.state.doc.nodeAt(editor.state.selection.from)

  return [
    [
      {
        icon: DownloadIcon,
        to: node?.attrs?.src,
        download: true,
        tooltip: { text: 'Download' }
      }
    ],
    [
      {
        icon: TrashcanIcon,
        tooltip: { text: 'Delete' },
        onClick: () => {
          const { state } = editor
          const { selection } = state

          const pos = selection.from
          const node = state.doc.nodeAt(pos)

          if (node && node.type.name === 'image') {
            editor.chain().focus().deleteRange({ from: pos, to: pos + node.nodeSize }).run()
          }
        }
      }
    ]
  ]
}
</script>

<template>
  <B24Editor
    v-slot="{ editor }"
    v-model="value"
    content-type="markdown"
    class="w-full min-h-113"
  >
    <B24EditorToolbar
      :editor="editor"
      :items="items(editor)"
      layout="bubble"
      :should-show="({ editor, view }) => {
        return editor.isActive('image') && view.hasFocus()
      }"
    />
  </B24Editor>
</template>

With link popover

This example demonstrates how to create a custom link popover using the slot property on toolbar items and the Popover component.

  1. Create a Vue component that wraps a Popover with link editing functionality:
EditorLinkPopover.vue
<script setup lang="ts">
import type { Editor } from '@tiptap/vue-3'
import LinkIcon from '@bitrix24/b24icons-vue/outline/LinkIcon'
import LowerRightArrowIcon from '@bitrix24/b24icons-vue/outline/LowerRightArrowIcon'
import GoToLIcon from '@bitrix24/b24icons-vue/outline/GoToLIcon'
import TrashcanIcon from '@bitrix24/b24icons-vue/outline/TrashcanIcon'

const props = defineProps<{
  editor: Editor
  autoOpen?: boolean
}>()

const open = ref(false)
const url = ref('')

const active = computed(() => props.editor.isActive('link'))
const disabled = computed(() => {
  if (!props.editor.isEditable) return true
  const { selection } = props.editor.state
  return selection.empty && !props.editor.isActive('link')
})

watch(() => props.editor, (editor, _, onCleanup) => {
  if (!editor) return

  const updateUrl = () => {
    const { href } = editor.getAttributes('link')
    url.value = href || ''
  }

  updateUrl()
  editor.on('selectionUpdate', updateUrl)

  onCleanup(() => {
    editor.off('selectionUpdate', updateUrl)
  })
}, { immediate: true })

watch(active, (isActive) => {
  if (isActive && props.autoOpen) {
    open.value = true
  }
})

function setLink() {
  if (!url.value) return

  const { selection } = props.editor.state
  const isEmpty = selection.empty

  let chain = props.editor.chain().focus()
  chain = chain.extendMarkRange('link').setLink({ href: url.value })

  if (isEmpty) {
    chain = chain.insertContent({ type: 'text', text: url.value })
  }

  chain.run()
  open.value = false
}

function removeLink() {
  props.editor
    .chain()
    .focus()
    .extendMarkRange('link')
    .unsetLink()
    .setMeta('preventAutolink', true)
    .run()

  url.value = ''
  open.value = false
}

function openLink() {
  if (!url.value) return
  window.open(url.value, '_blank', 'noopener,noreferrer')
}

function handleKeyDown(event: KeyboardEvent) {
  if (event.key === 'Enter') {
    event.preventDefault()
    setLink()
  }
}
</script>

<template>
  <B24Popover v-model:open="open" :b24ui="{ content: 'p-0.5' }">
    <B24Tooltip text="Link">
      <B24Button
        :icon="LinkIcon"
        color="air-tertiary-no-accent"
        active-color="air-primary"
        size="sm"
        :active="active"
        :disabled="disabled"
      />
    </B24Tooltip>

    <template #content>
      <B24Input
        v-model="url"
        no-border
        autofocus
        name="url"
        type="url"
        size="sm"
        placeholder="Paste a link..."
        @keydown="handleKeyDown"
      >
        <div class="flex items-center mr-0.5">
          <B24Button
            :icon="LowerRightArrowIcon"
            color="air-tertiary-accent"
            size="sm"
            :disabled="!url && !active"
            title="Apply link"
            @click="setLink"
          />

          <B24Separator orientation="vertical" class="h-6 mx-1" />

          <B24Button
            :icon="GoToLIcon"
            color="air-tertiary-no-accent"
            size="sm"
            :disabled="!url && !active"
            title="Open in new window"
            @click="openLink"
          />

          <B24Button
            :icon="TrashcanIcon"
            color="air-tertiary-no-accent"
            size="sm"
            :disabled="!url && !active"
            title="Remove link"
            @click="removeLink"
          />
        </div>
      </B24Input>
    </template>
  </B24Popover>
</template>
  1. Use the custom component in the toolbar with a named slot:
<script setup lang="ts">
import type { EditorToolbarItem } from '@bitrix24/b24ui-nuxt'
import EditorLinkPopover from './EditorLinkPopover.vue'
import BoldIcon from '@bitrix24/b24icons-vue/outline/BoldIcon'
import ItalicIcon from '@bitrix24/b24icons-vue/outline/ItalicIcon'

const value = ref(`Select text and click the link button to add a link with the custom popover.

You can also edit existing links like [this one](https://bitrix24.github.io/b24ui/).`)

const toolbarItems = [
  [
    {
      kind: 'mark',
      mark: 'bold',
      icon: BoldIcon
    },
    {
      kind: 'mark',
      mark: 'italic',
      icon: ItalicIcon
    },
    {
      slot: 'link' as const
    }
  ]
] satisfies EditorToolbarItem[][]
</script>

<template>
  <B24Editor
    v-slot="{ editor }"
    v-model="value"
    content-type="markdown"
    class="w-full min-h-30 flex flex-col gap-4"
  >
    <B24EditorToolbar :editor="editor" :items="toolbarItems" class="sm:px-8">
      <template #link>
        <EditorLinkPopover :editor="editor" auto-open />
      </template>
    </B24EditorToolbar>
  </B24Editor>
</template>

API

Props

Prop Default Type
as'div'any

The element or component this component should render as.

editorEditor
color'air-tertiary-no-accent'"air-primary" | "air-primary-success" | "air-primary-alert" | "air-primary-copilot" | "air-secondary" | "air-secondary-alert" | "air-secondary-accent" | "air-secondary-accent-1" | "air-secondary-accent-2" | "air-secondary-no-accent" | "air-tertiary" | "air-tertiary-accent" | "air-tertiary-no-accent" | "air-selection" | "air-boost" | "link"

The color of the toolbar controls.

activeColor'air-tertiary-accent'"air-primary" | "air-primary-success" | "air-primary-alert" | "air-primary-copilot" | "air-secondary" | "air-secondary-alert" | "air-secondary-accent" | "air-secondary-accent-1" | "air-secondary-accent-2" | "air-secondary-no-accent" | "air-tertiary" | "air-tertiary-accent" | "air-tertiary-no-accent" | "air-selection" | "air-boost" | "link"

The color of the active toolbar control.

size'sm' "xs" | "md" | "xss" | "sm" | "lg" | "xl"

The size of the toolbar controls.

items EditorToolbarItem<EditorCustomHandlers>[] | EditorToolbarItem<EditorCustomHandlers>[][]
layout'fixed' "fixed" | "floating" | "bubble"
pluginKeyunknown

The plugin key. The plugin key for the floating menu.

updateDelayunknown

The delay in milliseconds before the menu should be updated. This can be useful to prevent performance issues.

resizeDelayunknown

The delay in milliseconds before the menu position should be updated on window resize. This can be useful to prevent performance issues.

shouldShowunknown

A function that determines whether the menu should be shown or not. If this function returns false, the menu will be hidden, otherwise it will be shown.

appendTounknown

The DOM element to append your menu to. Default is the editor's parent element.

Sometimes the menu needs to be appended to a different DOM context due to accessibility, clipping, or z-index issues.

getReferencedVirtualElementunknown

A function that returns the virtual element for the menu. This is useful when the menu needs to be positioned relative to a specific DOM element.

optionsunknown

The options for the bubble menu. Those are passed to Floating UI and include options for the placement, offset, flip, shift, arrow, size, autoPlacement, hide, and inline middlewares. The options for the floating menu. Those are passed to Floating UI and include options for the placement, offset, flip, shift, arrow, size, autoPlacement, hide, and inline middlewares.

b24ui { root?: ClassNameValue; base?: ClassNameValue; group?: ClassNameValue; separator?: ClassNameValue; }

Slots

Slot Type
item{ item: EditorToolbarItem<EditorCustomHandlers>; } & SlotPropsProps

Theme

app.config.ts
export default defineAppConfig({
  b24ui: {
    editorToolbar: {
      slots: {
        root: 'focus:outline-none',
        base: 'flex items-stretch gap-1.5',
        group: 'flex items-center gap-0.5',
        separator: 'w-px self-stretch bg-(--ui-color-design-tinted-na-stroke)'
      },
      variants: {
        layout: {
          bubble: {
            base: 'backdrop-blur-3xl bg-(--ui-color-bg-content-primary) border border-(--ui-color-divider-default) rounded-md p-1'
          },
          floating: {
            base: 'backdrop-blur-3xl bg-(--ui-color-bg-content-primary) border border-(--ui-color-divider-default) rounded-md p-1'
          },
          fixed: {
            base: ''
          }
        }
      }
    }
  }
})
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import bitrix24UIPluginVite from '@bitrix24/b24ui-nuxt/vite'

export default defineConfig({
  plugins: [
    vue(),
    bitrix24UIPluginVite({
      b24ui: {
        editorToolbar: {
          slots: {
            root: 'focus:outline-none',
            base: 'flex items-stretch gap-1.5',
            group: 'flex items-center gap-0.5',
            separator: 'w-px self-stretch bg-(--ui-color-design-tinted-na-stroke)'
          },
          variants: {
            layout: {
              bubble: {
                base: 'backdrop-blur-3xl bg-(--ui-color-bg-content-primary) border border-(--ui-color-divider-default) rounded-md p-1'
              },
              floating: {
                base: 'backdrop-blur-3xl bg-(--ui-color-bg-content-primary) border border-(--ui-color-divider-default) rounded-md p-1'
              },
              fixed: {
                base: ''
              }
            }
          }
        }
      }
    })
  ]
})

EditorSuggestionMenu

A slash command menu that displays formatting and action suggestions when typing /.

ContentSearch

A ready-to-use Command Palette component for your documentation.

Releases
 Published under MIT License.

Copyright © 2024-present Bitrix24