Editor guide

🇫🇷 Version française

Editor guide

The editor is built into the card. It edits a copy of the plan, shows it live, and writes it into the dashboard configuration when you Save.

• Opening the editor
• Toolbar · Keyboard shortcuts
• Drawing and snapping
• Selecting, moving, grouping
• Undo, drafts, saving and versions
• The Add catalogue
• Floating toolbar and edit dialogs (new in 0.2.0)
• Workshops: Create a widget · Create an opening · Create furniture
• My templates
• Export and import
• Layers · Ambience and animations · Settings
• On a phone or tablet
• Clean up the plan

Opening the editor

The Edit plan button (ruler and pencil) sits at the top right of the card. It is shown only:

• to Home Assistant administrators;
• when editor: false is not set (⚙ Settings › General › Edit button (pencil); to get a hidden button back, remove editor: false in the card's code editor);
• outside the card picker and outside the dashboard's own edit mode.

When it opens, the drawing area is the plan plus a 5 m margin on every side (it grows when you draw near the edge). On a phone, the view is framed on the plan. If the plan contains elements without valid coordinates (a room without three points, a wall without ends), a message says how many will be removed at the next save.

Toolbar

On a desktop, from left to right:

Group	Button	Shortcut
History	Undo · Redo	Ctrl+Z · Ctrl+Y (or Ctrl+Shift+Z)
Tools	Select	V
	Wall	M
	Boundary / fence	L
	Opening	O
	Rectangular room with walls	R
	Freeform room	P
	Text	T
Grid	Grid: 5 cm ▾: grid step 1, 5, 10 or 25 cm (also the snapping and arrow-key step)
	Reframe: the whole plan with the 5 m margin
Dialogs	Layers · Ambience and animations
Files	Clean up the plan (magic wand, see Clean up the plan) · Export / import the plan (YAML, JSON) · Settings ⚙ · Keyboard shortcuts ⌨	?
End	Add	A
	Exit · Apply (save and keep editing) · Save (save and leave; a dot = unsaved changes)	Ctrl+S = Apply

On a phone the bar has two rows: Grid, ⋮ More tools (Reframe, Layers, Ambience and animations, Clean up the plan, Restore a plan from before clean-up when there is one, Import / export, Settings), Add, Exit and Save on top; Undo, Redo and the seven tools below.

Keyboard shortcuts

Press ? (or the ⌨ button) to show this list in the editor.

Keys	Action
Ctrl+Z · Ctrl+Y / Ctrl+Shift+Z	Undo · redo
Ctrl+S	Apply: save without leaving (also while typing in a field)
Enter · double click	Open the edit dialog of the selection
A	Add an object or a widget
Esc	Cancel the tool, deselect, close a dialog (← goes back to the previous one)
V M L O R P T	Select, Wall, Boundary / fence, Opening, Rectangular room, Freeform room, Text
Click · Ctrl+click (or Shift+click)	Select · add to or remove from the selection
Drag on empty space	Selection box
Ctrl+A	Select all (except hidden and locked layers)
Arrows · Shift+arrows	Move by one grid step · by ten steps
Delete (or Backspace)	Remove
Ctrl+D	Duplicate
Ctrl+G · Ctrl+Shift+G	Group · ungroup
Space+drag · middle button	Pan the view
Ctrl+wheel · pinch	Zoom
Alt (held)	No snapping
Shift (while drawing)	Free angle
Enter · right click · double click	Finish a wall, fence or freeform room

On a Mac, Cmd works like Ctrl.

Drawing and snapping

Tool	How
Wall (M)	Click to chain segments; finish with Enter, Esc, right click or double click (Done on touch screens). Each segment is one undo step.
Boundary / fence (L)	Same as walls; drawn as a thinner line (fences).
Rectangular room (R)	Click two opposite corners: the room and its four walls are created, without duplicating a wall that already exists. A bubble shows width × height · area. Then set the exact Width and Height (cm) in its edit dialog.
Freeform room (P)	Click every corner; close on the first corner, with Enter or Done.
Opening (O)	Click both ends on a wall. The outside side is set automatically (away from the indoor room). Armed from a preset, the sensors are looked up in the room.
Text (T)	One click places a text and selects its field. Add › Info box places a box of live values instead.

Snapping, in this order: hold Alt for none; while drawing, a segment within about 15° of horizontal or vertical is straightened (Shift for a free angle); points snap to wall, fence and opening ends and room corners within 12 px; otherwise to the grid. There is no 45° snapping and no measuring tool: the bubble near the cursor shows lengths, sizes and areas.

Room corners: drag a corner; the dot in the middle of an edge adds a corner; a double click on a corner removes it (at least three remain). Changing Width / Height of a rectangular room moves its right and bottom edges with their walls, openings and furniture; a wall shared with a neighbour stays and a new wall is added.

Furniture moves on the grid (Alt: 1 cm) and sticks to the inside of horizontal and vertical walls. Corner handles resize it (Shift keeps the proportions).

Selecting, moving, grouping

• Rooms: the first click selects the room; once it is selected, drag it to move it with the furniture and sub-areas inside. The label can be dragged alone. A second click on a sub-area selects the room around it.
• Box selection: drag on empty space; keeps what is fully inside. Ctrl or Shift adds to the selection.
• Multiple selection (details): counts, Align (left, centre, right, top, middle, bottom) with two or more badges, texts or furniture, Distribute horizontally or vertically with three or more, Group, Duplicate, Delete.
• Groups (groups): the first click on a member selects the whole group, a second click the element alone.
• Duplicate offsets the copy by 40 cm; there is no copy / paste between plans (use templates or export).
• Delete shows a message with Undo. Deleting a room keeps its furniture and sub-areas and offers to delete them too.
• Rotate (furniture): ±15° and ±90° buttons, or the angle field.

Undo, drafts, saving and versions

• Undo / redo: 150 steps. The Undo button of a message only works if nothing else changed since.
• Draft: every change is kept in the browser (localStorage). When you open the editor and a draft exists, a message offers Resume or Delete. Leaving the page with unsaved changes asks for confirmation.
• Apply (Ctrl+S) saves and keeps the editor open (Plan saved.); Save saves and leaves the editor. New in 0.2.0. Both write into the dashboard (lovelace/config/save). The card is found by its id (written on the first save if missing). If the dashboard card changed in the meantime (another browser, the YAML editor), a dialog Plan changed elsewhere offers Export my plan, Cancel or Overwrite with my plan. A dashboard in YAML mode cannot be saved: export the plan and paste it into your YAML.
• A Maquette dashboard created from Add dashboard is converted to normal views on the first save.
• Previous versions: the last five versions replaced by a save are kept in the browser and listed in the Export / import dialog with Load.
• Exit with unsaved changes asks: Keep editing, Discard changes or Exit (the draft stays in the browser).

The Add catalogue

Add (key A) opens the catalogue. Tabs: All, Rooms, Devices, Openings, Furniture, Widgets, and My templates once you have some. The search box ignores accents and case; every word must match; it searches all tabs, ready-made widgets included, and lists name matches first.

Tab	Entries
Rooms and drawing	Home Assistant area (draw a room linked to an area, with its devices) · All my HA areas (one room per area, see Getting started) · Rectangular room · Freeform room · Wall · Boundary / fence · Text · Info box
Devices	Light (halo) · Plug / switch · Metered device (value and "active" from a power sensor) · Camera (blinks) · Motion sensor · Thermostat · Sensor (value) · TV / media · Any device
Openings	Create an opening · Window + shutter + contact · Window + contact · Tilt and turn window · Door + shutter + contact · Door + contact · French window + shutter + contact · Sliding bay window · Interior door · Garage door · Gate
Furniture	Create furniture · Sub-areas (Kitchen, Shower, Dining area, Lounge area, Office corner, Walk-in closet, Laundry room, Entrance, Sub-area) · 45 symbols in 8 categories, see Furniture
Widgets	The 10 basic types and All widgets (65 ready-made, see Widgets); ← / → on a tile chooses the left or right panel
My templates	Your saved badges, openings and widgets (custom furniture shows in its own category)

Devices ask for an entity (full picker, filtered by domain), then a click on the plan. Fields left empty are highlighted in orange "to fill in".

Entity pre-fill

Openings, ready-made widgets and connected furniture templates look for matching entities (domain, device class, unit, words in the name) in the room they go to:

• one match is linked;
• several open a short list (In "room" first, then Elsewhere) with Other entity… (full picker) and Skip;
• none leaves the field highlighted "to fill in".

The room is its area, else the Home Assistant area with the same name (accents and case ignored), else the only area whose name contains the room name or is contained in it (four letters at least). Details per element: Entities.

Floating toolbar and edit dialogs

New in 0.2.0: the side panel is gone. Every element (room, opening, badge, furniture, text, info box, wall, fence, widget, summary chip) works the same way:

1. Click it: its handles appear with a small floating toolbar next to it, kept outside the element and in view (it follows zoom and pan): Edit, Duplicate, lock, Bring to front / Send to back, Delete.
2. Edit, a double-click or Enter opens its edit dialog, in tabs, with a live preview: the element cropped from the real plan in its room (a widget or a chip shows itself). Ctrl+Z works inside; Apply keeps the change, Esc closes. Full screen on a phone.
3. An element picked inside a dialog (or in Layers) opens its own dialog; ← or Esc goes back.

Desktop	Phone

Element	Tabs and main fields
Room	General: name, width / height (rectangles), temperature, humidity, Advanced, Outdoor, Sub-area, Room view on tap, Show label · Home Assistant area: link, Add the area's devices, To place on the walls · Room view: left / right panels, Automatic buttons, Show related automations, Action buttons
Opening	General: name, type, Leaves, Opening (none, left, right, sliding), Opens outward, outside side, Bay (grouped leaves) · Sensors: contact (Add a sensor), shutter, motorized entity, shutter only · Light: door glazing, sill, height, roof overhang, slats · Card · Animation. Footer: Edit in the workshop
Badge	General: entity, name, icon, Color when active, Halo when on, value shown, blinks when active · Advanced settings: active entity or attribute, Active above, unit, decimals, halo limited to a room · Card · Animation
Furniture	General: name, type, width / depth, chairs, orientation and Mirror, Position · Connected: entity, value, colour, tap, protected, card, Fill from device, Merge with a nearby badge · Animation (once connected). Footer: Customize the shape, template
Text / Info box	General: text, size, position · for an info box: General (title, style boxed or subtle, size, position) and Entities (n): its entity rows
Wall / fence	General: start and end coordinates. Footer: To boundary / To wall, Split in two
Widget	General: title, icon, accent colour and the fields of its type; move up / down, to the other panel, duplicate, template
Summary chip	General: entity chip fields, alert, hide rule, show (always / nobody home / somebody home), icon, stacking. Footer: ← / → to move it

Every dialog has Hide in view and Bring to front / Send to back (order in its layer). Help texts are behind ⓘ.

Room	Opening

Multiple selection

Select several elements (box, Ctrl+click, Ctrl+A): the floating toolbar acts on all of them (Edit, Duplicate, lock, Delete). Edit opens a dialog with the shared settings (General: Align, Hide in view, group name), the list of the selection (Selection) and grouped actions (Group, lock, duplicate, delete), previewed together.

Lock, named colors, badges in their room

New in 0.2.0:

• Lock (padlock in the floating toolbar, the edit dialog and Layers › Plan elements; locked: true on a room, opening, badge, text or furniture): still selectable and editable, but no longer moved or resized by the mouse or the arrow keys, and a click on it goes to the element underneath. Walls and fences lock by layer.

• Named colors (⚙ Settings › Display › Named colors, palette): offered in every color picker; an element using a name follows the palette when it changes.

  palette:
    accent: "#e8710a"
    wall_blue: "rgb(30, 90, 160)"
  badges:
    - {entity: light.living_room, pos: [200, 150], color: accent}

• Badges only in their room view: zoom_only: true on a badge, or badge_style.zoom_only: true for all of them (⚙ Settings › Device badges).

Card section (opening, badge, furniture): On tap, in view (default, open its card, more info, nothing), Protected, Always ask for confirmation (on / off confirmed, see Security), card title, "More info" button, its widgets, Add widget, Fill from device (a preview of suggested widgets from the same device, then Add or Replace card), Save card as template. While the element is selected, the right column shows its real card.

Workshops

A workshop is a two-step dialog: 1. Choose the type, then 2. Settings with a live preview. Add places the result, Save to My templates keeps it for later (optionally with Choose entities each time). Full screen on a phone.

Create a widget

Add widget › Create a widget: pick one of the 11 types (Tile + graph, Gauge, Entity list, Control, Lock, Thermostat, Room climate, Periods, Live rate, Electric vehicle, Divider), set the essentials (title, icon, entities, unit, min / max…) and the panel (left or right; a card when opened from a card).

Create an opening

Add › Openings › Create an opening: choose a preset, then name, type, leaves, opening side, outward, sensors (contact, shutter, motor; left empty, they are looked up in the room when placed) and animation, with a preview on a piece of wall. Add arms the Opening tool: click both ends on a wall. A drawn opening reopens in the workshop with Edit in the workshop to apply another preset without redrawing it.

Create furniture

Add › Furniture › Create furniture: start from a basic shape (rectangle, rounded rectangle, circle, L shape) or from any catalogue piece, then set the name, size, category, search words, colour, an optional entity and the list of shapes. Shapes are edited directly in the preview:

• click a shape to select it (its row is highlighted), drag it, resize it with its 8 handles (Shift keeps the proportions);
• drag the points of lines and polygons; the + in the middle of an edge adds a point; a long press, Delete or the row button removes one (a polygon keeps at least 3);
• snapping to a 5 cm grid and to the edges and centres of the piece and of the other shapes, with guides; Alt or the magnet button turns it off; shapes stay inside the piece;
• arrows move by 1 cm (Shift: 10 cm); Ctrl+Z / Ctrl+Y undo inside the workshop; Enlarge makes the preview bigger.

A placed piece opens in the same workshop with Customize the shape (catalogue piece) or Edit the shape (custom piece). The YAML is described in Furniture › Custom furniture.

My templates

Save almost anything for reuse, in the card configuration (templates):

From	Button	Option
A badge, an opening, a widget	Template in its edit dialog	Keep the entities (otherwise they are asked at each use)
A piece of furniture	Template	Keep the entities (only if it is connected)
A card	Save card as template	Keep entities
A workshop	Save to My templates	Choose entities each time

Templates appear in Add › My templates (custom furniture in its catalogue category, with ✎ to edit it); 🗑 deletes one (undo with Ctrl+Z). Entity fields to choose (ask) are emptied and highlighted for widgets, looked up in the room for openings and furniture.

Export and import

The Export / import button shows the whole plan in YAML or JSON (English keys, exactly as in the dashboard):

• Copy, Download (plan-<id>.yaml or .json), Open a file… (.yaml, .yml, .json);
• paste a plan and click Import: it replaces the current plan in one undoable step and keeps the card type and id; Save to keep it;
• Previous versions: Load puts a saved version in the text box, then Import.

Import checks the structure (lists, room outlines) and refuses plans written with the former French keys (pieces, murs…). A plan that differs from the current one first shows Check before importing: the services of its room buttons (sensitive ones marked), the entities its widgets control, its links, the values removed as invalid and the dashboard keys ignored; nothing is applied until you click Import. Only import plans from people you trust: see Security › Import check.

Layers

Layers (a dialog since 0.2.0) lists the layers in two groups, Above the drawing (room labels, area labels, devices, texts) and Drawing (rooms, sub-areas, light halos, furniture, boundaries, walls, openings). Drag a row (or ↑ / ↓) to reorder, 👁 to hide a layer in the view, 🔒 to let clicks go through in the editor. Plan elements lists every room, device, opening, piece of furniture, text, widget, chip and group: a click opens its edit dialog, Esc comes back to Layers. See Drawing the plan › Layers.

Ambience and animations

New in 0.2.0: a dialog in 6 tabs, like ⚙ Settings: General (ambience: intensity, north, day and night, weather, traces), Light (light, with a sample room previewed at any time of day and in any weather), People, Energy, Animations (per event) and Alerts (full-plan alerts). The ambience is drawn in the editor only while it is open (a live preview on the plan behind). People › Place on the plan lets you drag the avatars of the people at home.

Desktop	Phone

Settings

⚙ Settings holds the card-wide options, in tabs: General, Display, Features, Rooms and legend, People on the plan (when people are shown), Device badges, Interaction. Display also holds Named colors and a link to the Light tab. Changes are previewed live and can be undone; a setting put back to its default is removed from the YAML; a number out of range is refused. The full list of fields and keys is in Reference › Global settings.

Under the title: the installed version (Maquette 0.2.0) and two links, Documentation (the repository's README) and Report an issue (its issues). Give the version when you report a problem.

On a phone or tablet

• The bar has two rows; less frequent buttons are in ⋮ More tools.
• Touch an element for its floating toolbar; its edit dialog and the other dialogs are full screen.
• Finish walls, fences and freeform rooms with Done. Pinch to zoom.
• The Add widget dialog and the workshops are full screen; in Create furniture the preview stays at the top while you scroll the form, and a long press removes a point.
• Keyboard hints and the shortcuts button are hidden on touch-only screens.

Editor	More tools