# Drawing board

A React block (a whole screen) in [Beamline](https://beamline.io/)'s [Research & design](https://beamline.io/components/apps/research-design) app. Live demo: https://beamline.io/components/drawing-board

A whiteboard a team already knows how to use, like FigJam: tools in a floating bar at the bottom (Select V, Hand H, Sticky note S, Shape R/O/D, Connector X, Text T, Marker P, Section Shift+S), each with a tooltip and its key, and the active tool's choices (note colour, which shape, marker colour and width, straight or elbow) just above it. Click to place a sticky note and type at once; its words fit the note. Shapes take a label, sections frame an area and carry the notes inside when moved, connectors attach to the objects they join and follow them, with arrowheads and a label. Click, Shift-click or drag a marquee to select; drag to move with snap guides; resize from the handles; arrow keys nudge; Delete, Cmd/Ctrl+D, copy and paste, bring forward and back. Every change is one undo step and undo brings back the selection. The selection gets a small toolbar above it (colour, text size and alignment, connector path and arrowheads, duplicate, delete, more) with the full style editor in a popover: stroke, background (none, a colour, or a gradient edited stop by stop), stroke width and dash, opacity, Mixed where the selection disagrees. The board pans and zooms by wheel, pinch or Ctrl + wheel, Space-drag and the hand, with zoom controls (−, %, +, fit) and a dot grid that scales; the first view fits the whole board. Touch: one finger pans the bare board, two pinch, a tap places a note. Colours are stored as role names and repaint with the look. Export draws its preview from the same frozen snapshot it saves: selection or everything, transparent or on a background, scale with the output size in pixels, PNG or SVG, the editable scene included or not; a cancelled save says nothing was saved and a failure keeps the choices.

## Use it for

- A team board: retros, brainstorms, user-flow maps and diagrams with sticky notes, shapes, connectors and sections.
- A sketching or diagram canvas with a style editor and image export.

## Not for

- 3D or CAD models ([model-workbench](https://beamline.io/components/model-workbench)).
- Executable node graphs with typed ports ([workflow-builder](https://beamline.io/components/workflow-builder)).

## Anatomy

- board: a dot grid that pans and zooms; sections (a tinted frame with its title above), sticky notes, shapes with labels, text, marker strokes, connectors with arrowheads and labels
- tools: a floating bar at the bottom: Select, Hand, Sticky note, Shape, Connector, Text, Marker, Section; the active tool's choices and a one-line hint above it
- top right: Undo, Redo, Export; top left: the board's name
- zoom: Zoom out, the level (click for 100%), Zoom in, Fit everything
- selection: an outline with eight resize handles, four connection dots on a single object, a selected connector's accent band and end handles, a marquee, snap guides
- selection toolbar: Colour, Text (size and alignment), connector path and Arrowheads, Style (the full editor), Duplicate, Delete, More (edit text, order, export selection)
- style editor: Stroke swatches, Background none, swatches, Gradient; Stroke width; Stroke style; Opacity; Mixed where the selection disagrees
- gradient editor: the bar over a checkerboard with draggable stops, the chosen stop's colour, position and opacity, the angle, Add stop, Remove stop, Cancel and Apply
- export: the preview on a checkerboard or background, What, Format, Scale, Background, Include the editable scene, the output size, Export

## States

- empty board, a full board fitted to the room, a tool active with its hint, a note being typed, a shape being drawn, a connector being dragged to its target (the target outlined), a marker stroke
- nothing selected, one selected (toolbar, handles, connection dots), several selected, a connector selected, marquee in progress, moving with snap guides, resizing
- panned, zoomed in or out, the hand or Space held
- single values, mixed values, property unsupported (a line's background, a note's outline), transparent fill, gradient open, colour typed but not yet valid, two stops left
- export preview, selection only, everything, transparent, encoding, saved, save cancelled, save failed
- narrow room: the hand tool folds away (a finger pans) and zoom moves up beside the actions

## Keyboard

- V select, H hand, S sticky note, R rectangle, O ellipse, D diamond, X or L connector, T text, P marker, Shift+S section; Escape goes back to Select, then clears the selection
- Ctrl or Cmd+Z undo, with Shift (or Ctrl+Y) redo; Ctrl or Cmd+D duplicate; Ctrl or Cmd+C, X, V copy, cut and paste; Ctrl or Cmd+A select all; Delete or Backspace removes the selection and the connectors attached to it
- Tab and Shift+Tab select the next and previous object while one is selected; Enter edits its words; Escape (or a click elsewhere) keeps them; arrow keys nudge 1, with Shift 10
- ] and [ bring forward and send backward, with Ctrl or Cmd to the front and back
- + and − zoom, Shift+0 100%, Shift+1 fit everything, Shift+2 zoom to the selection; Space and drag pans
- A gradient stop moves with the arrow keys (Shift for bigger steps); Delete removes it while more than two remain

## Motion

Nothing animates and no frame runs at rest. Objects follow the pointer while drawn, moved or resized; a dragged group is shifted on screen without re-rendering and placed on release; the view follows the wheel, the pinch and the drag one to one.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `shapes` | `Shape[]` | — | The board's objects (controlled). Stickies, shapes, text, sections, connectors and marker strokes. |
| `defaultShapes` | `Shape[]` | — | The board's objects when uncontrolled. |
| `onShapesChange` | `((shapes: Shape[]) => void)` | — | Every committed change: a drag, a resize, a typed note, a style. Not called while a gesture is in progress. |
| `defaultSelected` | `string[]` | — | Ids selected at first. |
| `defaultTool` | `Tool` | — | The tool at first; "select" by default. |
| `title` | `string` | — | The board's name, shown top left. |
| `onExport` | `((req: ExportRequest) => Promise<ExportResult>)` | — | Writes the export; resolve with the saved file's name or that the save was cancelled. |
| `locale` | `string` | — |  |
| `className` | `string` | — | Classes on the documented visual root; no override by default. |
| `style` | `CSSProperties` | — | Inline styles on the documented visual root; no overrides by default. |
| `ref` | `Ref<HTMLDivElement>` | — | Receives the documented native target or imperative handle; omitted by default. |

## Built from

- [toggle-group](https://beamline.io/components/toggle-group)
- button
- tooltip
- popover
- [dropdown-menu](https://beamline.io/components/dropdown-menu)
- slider
- [number-field](https://beamline.io/components/number-field)
- input
- dialog
- [segmented-control](https://beamline.io/components/segmented-control)
- switch

## Dependencies

`lucide-react`

## Import

```tsx
import { DrawingBoard } from "@beamline/drawing-board";
```

## Get it

Drawing board is part of Beamline UI. Install the parts you need in your React app as compiled packages or editable source. [Get Beamline](https://beamline.io/checkout?pack=complete) · [Connect your agent](https://beamline.io/connect)

## More in Research & design

- [Research synthesis](https://beamline.io/components/research-synthesis): A research study turned into evidence in one place. Transcripts: passages marked as accepted highlights or as the assistant's suggestions (dashed)…
- [Study setup](https://beamline.io/components/study-setup): Set up an unmoderated test and its screener. Test: what's tested (a website, a prototype by its share link, an app by its store page), who takes it…
- [Study flow](https://beamline.io/components/study-flow): A study's blocks in order, each with where people go next. A block that routes by its answer (multiple choice, scale, open question, prototype task) has…
- [Participant review](https://beamline.io/components/participant-review): One participant's session, answer by answer, beside the list of everyone who took the study. The list filters (finished, left early, with a recording)…
- [Click heatmap](https://beamline.io/components/click-heatmap): One screen of a usability task as it looked (your prototype's frame or a page built from your parts, scaled into a phone) with where people clicked over…
- [Tree test](https://beamline.io/components/tree-test): A tree test: build a navigation tree and read where people went. Build: pages added at the top or under any page, indented under the page above or moved…
- [Prototype task](https://beamline.io/components/prototype-task): A prototype task in a study. The linked prototype refreshes from the design keeping the task and paths (a start screen gone from the new version said, a…
- [Task results](https://beamline.io/components/task-results): A usability task's results, from headline outcomes down to paths and screens. Outcomes (direct success, indirect success, gave up) say their share and…
- [Matrix question](https://beamline.io/components/matrix-question): A matrix question and the participant's side of it, side by side. Rows (up to ten) share one set of choices (two to seven); Enter adds a row, several…
- [Prototype review](https://beamline.io/components/prototype-review): Reviewing a design file's clickable prototype. Present: the board on a stage with its wireframe, the flow chosen (an unavailable one can't be), Back…
- [Report builder](https://beamline.io/components/report-builder): Build a chart from your metrics without code: choose metrics, how to group them over time, an optional breakdown, filters, the range and the chart, see…
- [Report library](https://beamline.io/components/report-library): A business's reports in one place. The directory: reports by topic and group with search, each with what it answers; one this person can't open says why…
- [Review page builder](https://beamline.io/components/review-page-builder): Building the page reviewers use to go through records one by one. The queue of records (one with no title shows its id instead of a blank); the record as…
- [Database builder](https://beamline.io/components/database-builder): What a database does for the people who use it, built in one place. Templates: starting values per property (a relation default points at an existing…
- [Workflow builder](https://beamline.io/components/workflow-builder): Automation rules for a SaaS without code: a trigger, conditions built with the query builder that branch into Yes and No, actions and waits, drawn as a…
- [Workflow library](https://beamline.io/components/workflow-library): The automation library: every automation as a row (what starts it, whether it's live, a draft or paused, who owns it, when it last ran, and its runs this…
- [Model workbench](https://beamline.io/components/model-workbench): A CAD model's workbench around a large isometric scene of its bodies, each shaded from its material's appearance with a soft ground shadow and an axis…
- [Component properties](https://beamline.io/components/component-properties): A design system component from three sides. Its variants as a matrix on two chosen properties, the others filtering it, each cell drawing the variant; a…
- [Slot editor](https://beamline.io/components/slot-editor): Slots in a design system component, from making to filling. The main component's layer tree with a checkbox per layer: a nested frame converts to a slot…

Part of [Beamline UI: polished, editable React components and complete screens for custom applications](https://beamline.io/). [Build your own style from any look; tokens, fonts, radii, motion; not only colours](https://beamline.io/docs/customize).