telva

Embeddable React whiteboard editor for teams that want fast integration and deep customization.

Install

npm i telva

Peer dependencies

• react >= 16.8
• react-dom >= 16.8

Why teams use telva

• Single-component integration (<Telva />) for full editor experiences.
• Production-ready shape system: draw, pen, text, sticky, arrows, media, geometry shapes, and groups.
• Flexible UI presentation: standard interface or minimal variant, with toolbar at top or bottom.
• Rich style controls with fill, border, typography, and gradient-capable rendering.
• Extensible runtime through callbacks, external persistence hooks, and React component registry.

Quick start

import { Telva } from 'telva'

export function App() {
  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <Telva />
    </div>
  )
}

Next.js (client-only)

import dynamic from 'next/dynamic'

;('use client')

const Telva = dynamic(() => import('telva').then((m) => m.Telva), {
  ssr: false,
})

export default function Page() {
  return <Telva uiVariant="minimal" toolbarPosition="top" />
}

Core API highlights

Telva exposes high-level integration props for product teams:

• document, currentPageId for controlled state bootstrap.
• onChange, onPersist, onPatch, onCommand for persistence/event pipelines.
• showUI, showMenu, showPages, showStyles, showTools, showZoom for UI composition.
• uiVariant (normal | minimal) and toolbarPosition (top | bottom) for layout strategy.
• reactComponents for custom, app-defined blocks rendered inside the editor.

Internal architecture (how it works)

• Telva.tsx composes UI panels, renderer bindings, internationalization, and editor lifecycle.
• TelvaApp is the orchestration engine (tool state, commands, undo/redo, events, sessions).
• TVDR centralizes state reads/selectors for fast and predictable data access.
• state/shapes/* provides shape-specific behavior through util classes (render, bounds, hit tests, transforms).
• Rendering and pointer plumbing are delegated to telva-core, while geometry math comes from telva-vec and telva-intersect.

Package scripts

yarn dev
yarn build
yarn test
yarn lint

License

AGPL-3.0-only