UI primitive components

Low-level UI components for building custom tldraw interfaces

The tldraw UI provides primitive components that can be used to build custom interfaces. These components are styled and designed to work seamlessly with the tldraw editor.

Button components

TldrawUiButton

A styled button component with support for different visual types.

import { TldrawUiButton } from 'tldraw'

function CustomToolbar() {
  return (
    <div>
      <TldrawUiButton type="primary" onClick={() => console.log('clicked')}>
        Primary
      </TldrawUiButton>
      <TldrawUiButton type="normal" onClick={() => console.log('clicked')}>
        Normal
      </TldrawUiButton>
      <TldrawUiButton type="danger" onClick={() => console.log('clicked')}>
        Delete
      </TldrawUiButton>
    </div>
  )
}

Props

type · 'normal' | 'primary' | 'danger' | 'low' | 'icon' | 'tool' | 'menu' | 'help' · required

Visual style of the button.

disabled · boolean

Whether the button is disabled.

isActive · boolean

Whether the button appears in an active state.

htmlButtonType · 'button' | 'submit' | 'reset'

HTML button type attribute.

onClick · (e: React.MouseEvent) => void

Click handler.

children · ReactNode

Button content.

TldrawUiButtonIcon

Icon component for use inside buttons.

import { TldrawUiButton, TldrawUiButtonIcon } from 'tldraw'

function IconButton() {
  return (
    <TldrawUiButton type="icon">
      <TldrawUiButtonIcon icon="tool-pencil" />
    </TldrawUiButton>
  )
}

TldrawUiButtonLabel

Label component for use inside buttons.

import { TldrawUiButton, TldrawUiButtonLabel } from 'tldraw'

function LabelButton() {
  return (
    <TldrawUiButton type="normal">
      <TldrawUiButtonLabel>Click me</TldrawUiButtonLabel>
    </TldrawUiButton>
  )
}

Input components

TldrawUiInput

A styled text input component with support for icons, labels, and keyboard shortcuts.

import { TldrawUiInput } from 'tldraw'

function SearchInput() {
  const [value, setValue] = React.useState('')
  
  return (
    <TldrawUiInput
      label="Search"
      icon="search"
      value={value}
      onValueChange={setValue}
      onComplete={(val) => console.log('Completed with:', val)}
      placeholder="Type to search..."
    />
  )
}

Props

label · string

Label text displayed above the input.

icon · string | TLUiIconType

Icon displayed on the right side of the input.

iconLeft · string | TLUiIconType

Icon displayed on the left side of the input.

iconLabel · string

Accessible label for the icon.

value · string

Controlled value.

defaultValue · string

Uncontrolled default value.

placeholder · string

Placeholder text.

autoFocus · boolean

Auto-focus the input on mount.

autoSelect · boolean

Auto-select input text on focus.

disabled · boolean

Whether the input is disabled.

onValueChange · (value: string) => void

Called when the input value changes.

onComplete · (value: string) => void

Called when Enter is pressed.

onCancel · (value: string) => void

Called when Escape is pressed.

onBlur · (value: string) => void

Called when the input loses focus.

onFocus · () => void

Called when the input gains focus.

Icon component

TldrawUiIcon

Displays an icon from the tldraw icon set.

import { TldrawUiIcon } from 'tldraw'

function CustomUI() {
  return (
    <div>
      <TldrawUiIcon icon="tool-pencil" label="Pencil" />
      <TldrawUiIcon icon="check" label="Checked" small />
      <TldrawUiIcon icon="trash" label="Delete" color="red" />
    </div>
  )
}

Props

icon · string | TLUiIconType | ReactElement · required

Icon identifier or custom React element.

label · string · required

Accessible label for the icon.

small · boolean

Display icon at small size.

color · string

Icon color (CSS color value).

invertIcon · boolean

Horizontally flip the icon.

className · string

Additional CSS class names.

Dropdown menu components

TldrawUiDropdownMenuRoot

Root container for a dropdown menu.

import {
  TldrawUiDropdownMenuRoot,
  TldrawUiDropdownMenuTrigger,
  TldrawUiDropdownMenuContent,
  TldrawUiDropdownMenuItem,
  TldrawUiButton,
} from 'tldraw'

function CustomMenu() {
  return (
    <TldrawUiDropdownMenuRoot id="custom-menu">
      <TldrawUiDropdownMenuTrigger>
        <TldrawUiButton type="menu">Menu</TldrawUiButton>
      </TldrawUiDropdownMenuTrigger>
      <TldrawUiDropdownMenuContent>
        <TldrawUiDropdownMenuItem>
          <TldrawUiButton type="menu" onClick={() => console.log('Item 1')}>
            Item 1
          </TldrawUiButton>
        </TldrawUiDropdownMenuItem>
      </TldrawUiDropdownMenuContent>
    </TldrawUiDropdownMenuRoot>
  )
}

Props

id · string · required

Unique identifier for the menu.

modal · boolean · default: "false"

Whether the menu is modal.

children · ReactNode · required

Menu content.

TldrawUiDropdownMenuTrigger

Trigger button for the dropdown menu.

Props

children · ReactNode · required

Trigger content (typically a button).

TldrawUiDropdownMenuContent

Container for menu items.

Props

side · 'bottom' | 'top' | 'right' | 'left' · default: "'bottom'"

Which side of the trigger to display the menu.

align · 'start' | 'center' | 'end' · default: "'start'"

How to align the menu relative to the trigger.

sideOffset · number · default: "8"

Distance from the trigger.

alignOffset · number · default: "8"

Offset along the alignment axis.

className · string

Additional CSS class names.

children · ReactNode · required

Menu items.

TldrawUiDropdownMenuItem

Wrapper for individual menu items.

Props

noClose · boolean

Prevent closing the menu when this item is clicked.

children · ReactNode · required

Item content (typically a button).

TldrawUiDropdownMenuCheckboxItem

Checkbox menu item.

import { TldrawUiDropdownMenuCheckboxItem } from 'tldraw'

function CheckboxMenuItem() {
  const [checked, setChecked] = React.useState(false)
  
  return (
    <TldrawUiDropdownMenuCheckboxItem
      checked={checked}
      onSelect={() => setChecked(!checked)}
      title="Enable feature"
    >
      Enable feature
    </TldrawUiDropdownMenuCheckboxItem>
  )
}

Props

checked · boolean

Whether the checkbox is checked.

onSelect · (e: Event) => void

Called when the item is selected.

disabled · boolean

Whether the item is disabled.

title · string · required

Title attribute for accessibility.

children · ReactNode · required

Item content.

TldrawUiDropdownMenuGroup

Groups related menu items.

import { TldrawUiDropdownMenuGroup } from 'tldraw'

function GroupedMenu() {
  return (
    <TldrawUiDropdownMenuContent>
      <TldrawUiDropdownMenuGroup>
        {/* Group 1 items */}
      </TldrawUiDropdownMenuGroup>
      <TldrawUiDropdownMenuGroup>
        {/* Group 2 items */}
      </TldrawUiDropdownMenuGroup>
    </TldrawUiDropdownMenuContent>
  )
}

TldrawUiDropdownMenuSub

Submenu container.

import {
  TldrawUiDropdownMenuSub,
  TldrawUiDropdownMenuSubTrigger,
  TldrawUiDropdownMenuSubContent,
} from 'tldraw'

function Submenu() {
  return (
    <TldrawUiDropdownMenuSub id="submenu">
      <TldrawUiDropdownMenuSubTrigger label="More options" />
      <TldrawUiDropdownMenuSubContent>
        {/* Submenu items */}
      </TldrawUiDropdownMenuSubContent>
    </TldrawUiDropdownMenuSub>
  )
}

Other primitive components

TldrawUiKbd

Displays keyboard shortcut hints.

import { TldrawUiKbd } from 'tldraw'

function ShortcutHint() {
  return (
    <div>
      Press <TldrawUiKbd>Cmd+Z</TldrawUiKbd> to undo
    </div>
  )
}

TldrawUiSlider

Slider input component.

import { TldrawUiSlider } from 'tldraw'

function OpacitySlider() {
  const [opacity, setOpacity] = React.useState(1)
  
  return (
    <TldrawUiSlider
      value={opacity}
      onValueChange={setOpacity}
      min={0}
      max={1}
      step={0.1}
      label="Opacity"
    />
  )
}

TldrawUiSelect

Select dropdown component.

import { TldrawUiSelect } from 'tldraw'

function FontSelector() {
  const [font, setFont] = React.useState('sans')
  
  return (
    <TldrawUiSelect
      value={font}
      onValueChange={setFont}
      options={[
        { value: 'sans', label: 'Sans Serif' },
        { value: 'serif', label: 'Serif' },
        { value: 'mono', label: 'Monospace' },
      ]}
    />
  )
}

Layout components

TldrawUiToolbar

Toolbar container with automatic layout.

TldrawUiContextualToolbar

Floating toolbar that appears near selected shapes.

TldrawUiDialog

Modal dialog container.

TldrawUiPopover

Popover container for floating UI elements.

Usage patterns

Building a custom toolbar

import {
  TldrawUiButton,
  TldrawUiButtonIcon,
  useTools,
  useEditor,
} from 'tldraw'

function CustomToolbar() {
  const tools = useTools()
  const editor = useEditor()
  
  return (
    <div className="custom-toolbar">
      {['select', 'draw', 'eraser'].map((toolId) => {
        const tool = tools[toolId]
        const isActive = editor.getCurrentToolId() === toolId
        
        return (
          <TldrawUiButton
            key={toolId}
            type="tool"
            isActive={isActive}
            onClick={() => tool.onSelect('toolbar')}
          >
            <TldrawUiButtonIcon icon={tool.icon} />
          </TldrawUiButton>
        )
      })}
    </div>
  )
}

Creating a custom menu

import {
  TldrawUiDropdownMenuRoot,
  TldrawUiDropdownMenuTrigger,
  TldrawUiDropdownMenuContent,
  TldrawUiDropdownMenuItem,
  TldrawUiDropdownMenuGroup,
  TldrawUiButton,
  TldrawUiButtonIcon,
  useActions,
} from 'tldraw'

function CustomMenu() {
  const actions = useActions()
  
  return (
    <TldrawUiDropdownMenuRoot id="custom-menu">
      <TldrawUiDropdownMenuTrigger>
        <TldrawUiButton type="menu">
          <TldrawUiButtonIcon icon="menu" />
        </TldrawUiButton>
      </TldrawUiDropdownMenuTrigger>
      
      <TldrawUiDropdownMenuContent>
        <TldrawUiDropdownMenuGroup>
          <TldrawUiDropdownMenuItem>
            <TldrawUiButton
              type="menu"
              onClick={() => actions['undo'].onSelect('menu')}
            >
              Undo
            </TldrawUiButton>
          </TldrawUiDropdownMenuItem>
          <TldrawUiDropdownMenuItem>
            <TldrawUiButton
              type="menu"
              onClick={() => actions['redo'].onSelect('menu')}
            >
              Redo
            </TldrawUiButton>
          </TldrawUiDropdownMenuItem>
        </TldrawUiDropdownMenuGroup>
      </TldrawUiDropdownMenuContent>
    </TldrawUiDropdownMenuRoot>
  )
}