grid-plan is a Vue3 component to create blueprints for rooms, datacenters, racks, etc.
Create available component types, and place, resize or delete them from the blueprint.
grid-plan ships with:
- config options to customize the looks of your blueprint
- slots to customize icons related to component types
- slots to create your available components menu and your inventory
pnpm add grid-plan
Three.js is an optional peer dependency, required only when displaying the 3D layout.
For 2D-only usage, install grid-plan and set showGrid3d to false:
<GridPlan :config="{ showGrid3d: false }" />The 3D layout is disabled by default. To use it, install Three.js:
pnpm add grid-plan threeYou can declare the component globally in your main.js:
import { createApp } from "vue";
import App from "./App.vue";
import { GridPlan } from "grid-plan";
const app = createApp(App);
app.component("GridPlan", GridPlan);
app.mount("#app");Or you can import it directly in your Vue file:
<script setup>
import { GridPlan } from "grid-plan";
</script>Create one controller with useGridPlan() and pass it to any grid, menu, or
inventory that should share state. Controls can live anywhere in the component
tree; create a separate controller for each independent plan.
<script setup>
import { ref } from "vue";
import {
GridPlan,
GridPlanMenu,
GridPlanInventory,
useGridPlan,
} from "grid-plan";
const placedItems = ref([
{ id: "server-1", typeId: 1, x: 0, y: 0, w: 1, h: 1 },
]);
const availableTypes = ref([
{ typeId: 1, description: "Server", icon: "server" },
]);
const config = ref({ showGrid3d: false });
const readonly = ref(false);
const plan = useGridPlan({ placedItems, availableTypes, config, readonly });
// Controller events also work when controls are outside GridPlan.
const stop = plan.on("change", (item) => console.log("Changed item", item));
// Call stop() to unsubscribe early. Subscriptions clear when its scope is disposed.
</script>
<template>
<aside>
<GridPlanMenu :plan="plan" title="Available types" :accordion="false" />
</aside>
<GridPlan :plan="plan" />
<footer>
<GridPlanInventory :plan="plan" title="Placed items">
<template
#default="{
item,
displayCoordinates,
focusItem,
deleteItem,
isFocused,
}"
>
<span>{{ item.description }} · {{ displayCoordinates.label }}</span>
<button :disabled="plan.readonly" @click="focusItem">
{{ isFocused ? "Unfocus" : "Focus" }}
</button>
<button :disabled="plan.readonly" @click="deleteItem">Delete</button>
</template>
</GridPlanInventory>
</footer>
</template>useGridPlan accepts plain values, refs, or getters for placedItems,
availableTypes, config, and readonly. Pass refs or getters when inputs can
change. It maintains editable copies of supplied items, stable generated IDs,
and synchronization with incoming item and type updates. Actions do not mutate
the original input arrays; persist updates through events as in the example below.
The returned controller is reactive, so use plan.items, plan.activeEntity,
plan.activeType, plan.hintedItem, plan.availableTypes, plan.config, and
plan.readonly directly, without .value. Use the controller methods to perform
actions rather than assigning these properties.
| Controller method | Behavior |
|---|---|
setActiveType(type) |
Choose a supplied type for new items |
createItem({ x, y }) |
Place a 1×1 item of the active type |
selectItem(item) / unselect() |
Update shared selection |
focusItem(item) |
Toggle shared selection |
hintItem(item) / hintItem(null) |
Show or clear hover feedback without selecting |
deleteItem(item) |
Remove a placed item |
recordChange(item) |
Notify consumers after a grid edit |
displayCoordinates(item) |
Get configured axis labels and the range label |
getItems() / getActiveItem() / getFocusState(item) |
Read current state |
on(event, callback) |
Subscribe and return an unsubscribe function |
Events are change, created, delete, select, unselect, and selectType.
GridPlan also forwards these events to its component listeners. Use either
subscription path for persistence to avoid handling the same action twice.
Readonly mode blocks creation, deletion, type selection, and item selection;
non-mutating hover hints remain available. Creation is a no-op when there are no available types or when coordinates are
non-integer, outside the grid, or overlap another item. Rejected creation emits no events.
Both controls accept plan (required), title (defaults to Menu or Inventory),
and accordion (defaults to true). They provide functional default content.
The menu's default slot receives availableType, isActive, and selectType.
Custom menu content owns its click handling: render a button with
@click="selectType" and :disabled="plan.readonly". Without a custom slot,
the menu renders its own buttons. The legacy GridPlan #availableType slot
still selects automatically when clicked, and may contain a button or plain text.
The inventory's default slot receives item, displayCoordinates, isFocused,
and bound focusItem, deleteItem, hintItem, and clearHint actions. Inventory
rows automatically hint their item on mouse entry and clear it on exit.
GridPlan still accepts availableTypes, placedItems, config, and readonly
as a convenience for a single grid. When plan is supplied, the controller owns
those inputs and takes precedence over the direct props.
Existing #availableType and #inventory slots remain available. When detected,
GridPlan renders GridPlanMenu and GridPlanInventory internally and forwards
the slot scopes. Without those slots, it renders no built-in controls. Existing
#before and #after slots and exposed component-ref methods also remain usable.
Avoid supplying a legacy control slot if you already render that control externally.
showMenu, showInventory, accordionMenuTitle, inventoryTitle, and
useAccordionMenu are no longer grid config properties. Control visibility with
v-if on the standalone controls, and move titles and accordion behavior to their
title and accordion props. Omit the corresponding legacy slot to hide an internal
control. Existing custom slots must disable their own action buttons in readonly mode;
the controller also guards these actions.
| Prop name | TS type | Required | Description |
|---|---|---|---|
| plan | GridPlanController | NO | Shared controller; takes precedence over direct inputs |
| availableTypes | GridPlanItemType[] | NO (defaults to empty) | The types of components that can be placed on the blueprint |
| placedItems | GridPlanItem[] | NO (defaults to empty) | Components already placed on the blueprint |
| readonly | boolean | NO (default: false) | Blueprint will be readonly if true |
| config | GridPlanConfig | NO (default config will be applied) | Configuration object to customize looks |
- Script:
import { ref } from "vue";
import { GridPlan } from "grid-plan";
const availableTypes = ref([
{
typeId: 1,
color: "#3366DD",
description: "server",
icon: "server",
iconColor: "#FFFFFF",
depth: 2, // optional item height (defaults to 1 (grid cell size) if not provided)
},
{
typeId: 2,
color: "#DD6633",
description: "power",
icon: "bolt",
iconColor: "#FFFFFF",
},
{
typeId: 3,
color: "#71a4a8",
description: "monitor",
icon: "deviceLaptop",
iconColor: "#1A1A1A",
},
]);
const placedItems = ref([
{ x: 0, y: 0, h: 1, w: 12, typeId: 1 }, // it's a server component
{ x: 0, y: 1, h: 4, w: 12, typeId: 3 }, // it's a monitor component
]);
// Config is optional
// You can provide a partial config, as missing attributes will use defaults
const config = ref({
abscissaType: "alphabetic",
coordinatesBackground: "#2A2A2A",
coordinatesColor: "#8A8A8A",
crosshairBackground: "#4A4A4A",
fontFamily: "Arial",
grid3dPosition: "top",
gridFill: "#3A3A3A",
gridHeight: 42,
gridHighlightColor: "#00FF00",
gridStroke: "#1A1A1A",
gridStrokeWidth: 0.02,
gridWidth: 12,
handleFill: "#FFFFFF",
handleSize: 0.3,
iconColor: "#1A1A1A",
showIcons: true,
nonSelectedOpacity: 0.3,
ordinatesType: "numeric",
showCrosshair: true,
showGrid3d: true,
showGrid2d: true,
tooltipColor: "#FFFFFF",
useGradient: true,
useShadow: true,
showBox: true,
boxThickness: 0.3,
boxHeight: 1,
boxColor: "#5A5A5A",
});
// Events
function selectType(menuItem) {
// Triggered when a menu item is selected
console.log("SELECT TYPE", menuItem);
}
function change(item) {
// Triggered whenever an item is changed
console.log("CHANGED", item);
}
function deleteItem(item) {
// Triggered whenever an item is deleted
console.log("DELETED", item);
}
function selectItem(item) {
// Triggered whenever an item is selected
console.log("SELECTED", item);
}
function createdItem(item) {
// Triggered whenever an item is created
console.log("CREATED", item);
}
function unselected() {
// Triggered when an item is unselected
// Pressing ESC will trigger unselect
// Selecting an already selected item will trigger unselect
console.log("BLUEPRINT IS NOW UNSELECTED");
}- Template:
<template>
<GridPlan
ref="plan"
:availableTypes
:config
:placedItems
@change="change"
@delete="deleteItem"
@select="selectItem"
@created="createdItem"
@unselect="unselected"
@selectType="selectType"
>
<!-- A slot to do whatever you need before the component -->
<template
#before="{ items, deleteItem, focusItem, getFocusState, activeEntity }"
>
<div>ACTIVE ENTITY: {{ activeEntity }}</div>
<div v-for="item in items">
{{ item.description }}
<button @click="deleteItem(item)">DELETE</button>
<button @click="focusItem(item)">DELETE</button>
FOCUS STATE: {{ getFocusState(item) }}
</div>
</template>
<!-- Create your available types menu -->
<template #availableType="{ availableType }">
<!-- The click event is managed by the component, that will select the type to be used when adding a component to the blueprint -->
<button>{{ availableType.description }}</button>
</template>
<!-- Create your inventory, which will be displayed inside a details element (target the .grid-plan-inventory css class to style) -->
<template #inventory="{ item, deleteItem, focusItem, isFocused }">
<div
:style="`display: flex; flex-direction:row; flex-wrap: wrap; border: 1px solid ${item.color};width: fit-content; padding: 6px 12px; gap:6px; ${isFocused ? 'background: #FFFFFF20' : ''}`"
>
<span>{{ item.description }}</span>
<span>x:{{ item.x }}</span>
<span>y:{{ item.y }}</span>
<span>h:{{ item.h }}</span>
<span>w:{{ item.w }}</span>
<button @click="deleteItem">DELETE</button>
<button @click="focusItem">
{{ isFocused ? 'UNFOCUS' : 'FOCUS' }}
</button>
</div>
</template>
<!-- Use your own svg icons for component types (not necessary if the icon provided is part of the available icons) -->
<template #componentIcon="{ placedItem, maxSize }">
<svg
v-if="placedItem.description === 'server'"
viewBox="0 0 24 24"
stroke-width="1.5"
stroke="#FFFFFF"
fill="none"
stroke-linecap="round"
stroke-linejoin="round"
:style="`width:${maxSize}px; position: absolute; transform: scale(0.8, 0.8)`"
>
<path stroke="none" d="M0 0h24v24H0z" fill="none" />
<path
d="M3 4m0 3a3 3 0 0 1 3 -3h12a3 3 0 0 1 3 3v2a3 3 0 0 1 -3 3h-12a3 3 0 0 1 -3 -3z"
/>
<path
d="M3 12m0 3a3 3 0 0 1 3 -3h12a3 3 0 0 1 3 3v2a3 3 0 0 1 -3 3h-12a3 3 0 0 1 -3 -3z"
/>
<path d="M7 8l0 .01" />
<path d="M7 16l0 .01" />
<path d="M11 8h6" />
<path d="M11 16h6" />
</svg>
</template>
<!-- Or use this slot to display a single letter or an icon font -->
<template #componentText="{ placedItem }"> {{ placedItem.icon }} </template>
<!-- A slot to do whatever you need after the component -->
<template
#after="{ items, deleteItem, focusItem, getFocusState, activeEntity }"
>
<div>ACTIVE ENTITY: {{ activeEntity }}</div>
<div v-for="item in items">
{{ item.description }}
<button @click="deleteItem(item)">DELETE</button>
<button @click="focusItem(item)">DELETE</button>
FOCUS STATE: {{ getFocusState(item) }}
</div>
</template>
</GridPlan>
</template>Item x and y values always remain zero-based numbers. Axis configuration only
changes display labels; existing item data, events, and the tooltip slot's
coordinates string keep their current behavior.
The inventory and tooltip slots additionally receive displayCoordinates:
<template #inventory="{ item, displayCoordinates }">
<span>{{ displayCoordinates.x }} / {{ displayCoordinates.y }}</span>
<span>{{ displayCoordinates.label }}</span>
<span>Raw position: {{ item.x }}, {{ item.y }}</span>
</template>For { x: 1, y: 2, w: 1, h: 1 } with the default axes, this is
{ x: 'B', y: '3', label: 'B-3' }. Both axis labels are strings. Larger items keep
the existing range label, for example B-3, C-4. The before and after slots
receive a displayCoordinates(item) function returning the same structure.
Display values react to axis configuration changes without modifying items.
For backend formats, use the optional exported conversion helpers explicitly:
import { formatCoordinate, parseCoordinate } from "grid-plan";
// Save alphabetic labels to a backend that expects them.
const payload = {
...item,
x: formatCoordinate(item.x, "alphabetic"), // 1 -> 'B'
y: formatCoordinate(item.y, "numeric"), // 2 -> '3'
};
// Convert stored labels back to numeric positions before passing to GridPlan.
const placedItem = {
...payload,
x: parseCoordinate(payload.x, "alphabetic"), // 'B' -> 1
y: parseCoordinate(payload.y, "numeric"), // '3' -> 2
};Choose storage formats independently of UI configuration. A backend expecting
zero-based numbers can keep using item.x and item.y directly. The helpers use
one-based numeric labels ('1' is position 0) and alphabetic labels ('A' is
position 0, 'AA' is position 26). Parsing accepts surrounding whitespace and
lowercase letters. Invalid labels, fractional or negative positions, and values
outside the supported safe-integer range throw errors. No conversion happens
automatically when loading or saving data.
All properties are optional. Defaults below use the dark theme; theme: "light" applies a light palette. Explicit color overrides take precedence over the theme.
| Attribute | TS type | Default | Description |
|---|---|---|---|
| theme | "dark" OR "light" | "dark" | Color theme; explicit configuration overrides its palette |
| abscissaType | "alphabetic" OR "numeric" | "alphabetic" | Display abscissa coordinates as letters or numbers |
| coordinatesBackground | string | "#2A2A2A" | Background color of the coordinates cells |
| coordinatesColor | string | "#8A8A8A" | Text color of the coordinates cells |
| crosshairBackground | string | "#4A4A4A" | Background color of the crosshair |
| fontFamily | string | "Arial" | Font used for all elements in the component |
| itemNameFontSizeRatio | number | 0.5 | 2D hovered and selected item name font size, in grid units |
| itemCoordinatesFontSizeRatio | number | 0.4 | 2D hovered and selected item coordinates font size, in grid units |
| itemNameOffsetY | number | 0 | 2D hovered and selected name Y offset in grid units; positive moves down |
| itemCoordinatesOffsetY | number | 0 | 2D hovered and selected coordinates Y offset in grid units; positive moves down |
| grid3dPosition | "top" OR "bottom" | "top" | Display 3d blueprint on top or below |
| gridFill | string | "#3A3A3A" | Background color of unused blueprint cells |
| gridHeight | number | 20 | The height of the blueprint in cell units |
| gridHighlightColor | string | "#FFFFFF" | The contour of available cells on hover |
| gridStroke | string | "#1A1A1A" | The color of grid lines |
| gridStrokeWidth | number | 0.02 | Grid line width in cell units |
| gridWidth | number | 20 | The width of the blueprint in cell units |
| handleFill | string | "#FFFFFF" | The color of resize handles |
| handleSize | number | 0.3 | The handle size |
| iconColor | string | "#1A1A1A" | Default item icon and #componentText slot color |
| showIcons | boolean | true | Show item icons in 2D and 3D, including the componentIcon slot |
| nonSelectedOpacity | number | 0.3 | The opacity of non selected components when a component is selected |
| ordinatesType | "alphabetic" OR "numeric" | "numeric" | Display ordinate coordinates as letters or numbers |
| showCrosshair | boolean | true | Show crosshair when hovering available cells |
| showGrid3d | boolean | false | Show the 3d blueprint |
| showGrid2d | boolean | true | Show the 2d blueprint |
| tooltipColor | string | "#FFFFFF" | The tooltip text color |
| showTooltip | boolean | true | Show item tooltips in both views |
| tooltipPosition | "top", "bottom", "left", "right" | "top" | Preferred item tooltip placement; flips automatically |
| tooltipBackgroundColor | string | "#202622f2" | Tooltip background color |
| tooltipBorderRadius | number OR string | 2 | Tooltip corner radius; numbers are pixels |
| tooltipLineHeight | number OR string | 1.5 | Tooltip line height; numbers are unitless |
| tooltipPadding | number OR string | "10px 14px" | Tooltip padding; numbers are pixels |
| tooltipBorder | string | "1px solid #ffffff30" | Tooltip CSS border |
| tooltipBoxShadow | string | "0 4px 16px #0003" | Tooltip CSS box shadow |
| tooltipWidth | number OR string | "fit-content" | Tooltip width; numbers are pixels |
| tooltipMaxWidth | number OR string | 280 | Tooltip maximum width; numbers are pixels; constrained to the map |
| tooltipMaxHeight | number OR string | 400 | Tooltip maximum height; numbers are pixels; constrained to the map |
| useGradient | boolean | true | Shows 2D components with a subtle gradient |
| useShadow | boolean | true | Show selected item with a drop shadow |
| showBox | boolean | true | Show a 'wall' around the grid |
| boxThickness | number | 0.3 | Box thickness, defaults to 1/3 of a grid cell |
| boxHeight | number | 1 | Box height, defaults to the same size as a grid cell |
| boxColor | string | "#5A5A5A" | Box color |
availableTypes[].icon accepts a built-in name (for example "server"), a raw SVG
d string, an array of d strings, or a custom definition. These icons render in
the 2D blueprint and on the top face of 3D items, and inherit iconColor. Strings and arrays use a 0 0 24 24
viewBox and an outline style.
const availableTypes = [
{
typeId: "custom",
description: "Custom equipment",
color: "#6385ed",
iconColor: "#ffffff",
icon: "M12 3L21 12L12 21L3 12Z",
},
{
typeId: "filled",
description: "Filled icon",
icon: {
paths: ["M4 4H28V28H4Z"],
viewBox: "0 0 32 32",
fill: "currentColor",
stroke: "none",
// strokeWidth: 1.44, // default for outline icons, in viewBox units
},
},
];Pass the contents of SVG d attributes, rather than an SVG markup string or an
image URL. The custom definition accepts paths as either a string or an array.
For arbitrary icon components or HTML, use the existing componentIcon slot.
Set config.showIcons to false to hide item icons in both views. It defaults to
true and also controls the componentIcon slot in both views. Text labels and delete-button
icons remain visible.
The componentIcon slot works in both views for items without a valid icon
definition. Load your library's CSS normally, then render its element:
<GridPlan :placed-items="placedItems" :available-types="availableTypes">
<template #componentIcon="{ placedItem, maxSize, iconColor }">
<i
:class="iconClasses[placedItem.typeId]"
aria-hidden="true"
:style="{
fontSize: `${maxSize * 0.7}px`,
lineHeight: 1,
color: placedItem.iconColor || iconColor,
}"
/>
</template>
</GridPlan>iconClasses maps your type IDs to your library's CSS classes. You can replace
i with span or a Vue icon component. Omit the type's icon property to use
this slot. maxSize is 32 pixels in both views. Size library icons in this
pixel-sized container using the font-size calculation shown above. The container scales to one grid unit, independently of the item's size,
so 1×1 items and larger items use the same icon size. In 3D, HTML icons lie on the
top face and follow the camera's perspective using CSS3DRenderer. They follow
edits, allow pointer interactions through them, and respect showIcons.
CSS3D icons are DOM elements layered over WebGL: other meshes do not occlude them. Use SVG path icons when WebGL depth occlusion is needed.
Item tooltips are enabled by default in both views. Set showTooltip to false to disable them:
config: {
showTooltip: false, // default: true
tooltipPosition: 'top', // top, bottom, left, or right
}The hovered item takes priority; when the pointer leaves it, the selected item's tooltip is shown. Tooltips also work in readonly mode. When enabled, they replace the inline item labels. The preferred placement flips to the opposite side, then tries the other sides to stay inside the map. Tooltips stay centered on the item along the chosen side and constrain oversized content to the available space. Their position follows item edits, camera movement, and container resizing.
All tooltip styles are configurable. These values preserve the default appearance:
config: {
showTooltip: true,
tooltipColor: '#FFFFFF',
tooltipBackgroundColor: '#202622f2',
tooltipBorderRadius: 2,
tooltipLineHeight: 1.5,
tooltipPadding: '10px 14px',
tooltipBorder: '1px solid #ffffff30',
tooltipBoxShadow: '0 4px 16px #0003',
tooltipWidth: "fit-content",
tooltipMaxWidth: 280,
tooltipMaxHeight: 400,
}Numeric sizes are pixels; CSS length strings such as '1rem', '50%', or
'calc(100% - 20px)' are also accepted. Numeric tooltipLineHeight values are
unitless. Automatic boundary limits still apply to maxWidth and maxHeight,
so a larger configured tooltip stays within its map. Styles apply to default
content and custom slot content alike. These controls are in the playground's
Tooltip section; the color text inputs also accept alpha values.
Customize the content with the tooltip slot:
<GridPlan
:config="{ showTooltip: true }"
:placed-items="placedItems"
:available-types="availableTypes"
>
<template #tooltip="{ item, coordinates, isSelected, view }">
<strong>{{ item.description }}</strong>
<div>{{ coordinates }} · {{ item.w }} × {{ item.h }}</div>
<div>Depth: {{ item.depth ?? 1 }}</div>
<small>{{ isSelected ? 'Selected' : 'Hovered' }} in {{ view }}</small>
</template>
</GridPlan>item is the full prepared element, including its ID, type information, icon,
texture, and any custom properties you supplied. coordinates is the formatted
coordinate range, isSelected indicates selection, and view is "2d" or "3d".
The TypeScript type GridPlanTooltipSlotProps is also exported.
The playground's Tooltip section controls visibility and preferred placement. Enable Custom tooltip slot in its toolbar to try the slot example.
Use the deleteIcon slot to replace the trash icon inside the selected item's floating
square delete button in both 2D and 3D. It sits outside the item, preferring
the right side and switching to the left, bottom, or top to fit near map edges.
It receives { item }, the selected item. The
button keeps its delete action, accessible label, and readonly behavior.
<GridPlan :placed-items="placedItems" :available-types="availableTypes">
<template #deleteIcon="{ item }">
<svg
viewBox="0 0 24 24"
style="width: 100%; height: 100%"
aria-hidden="true"
>
<path
d="M6 6L18 18M18 6L6 18"
fill="none"
stroke="currentColor"
stroke-width="2"
/>
</svg>
</template>
</GridPlan>You can also render an icon component in this slot. Size it to fill its container
with width: 100%; height: 100%. Omitting the slot preserves the default trash icon.
The 3D blueprint supports the same created, change, delete, select, and
unselect events as the 2D blueprint. Both views share the same items and selection.
- Click an empty floor cell to create an item using the active type.
- Hover an empty floor cell to see its highlight and coordinates.
showCrosshaircontrols the row and column shading. Cell highlights and hover coordinates are hidden in readonly mode. - Drag an item to move it. Movement snaps to grid cells.
- Select an item and drag one of its four corner handles to resize its footprint.
- Use the selected item's Depth field to change its vertical size, or Delete to remove it.
- Press Escape to cancel an ongoing drag and clear the selection.
- Drag empty space to orbit the camera; use the mouse wheel to zoom.
Moving and resizing respect grid boundaries and prevent overlaps. The readonly
prop disables selection, creation, movement, resizing, depth changes, and deletion.
Hover information and camera navigation remain available. Switching to readonly
clears the current selection.
To display only the 3D blueprint, install the optional three peer dependency and use:
<GridPlan
:placed-items="placedItems"
:available-types="availableTypes"
:config="{ showGrid2d: false, showGrid3d: true }"
/>The menu, inventory, and slots remain available in this mode. The 3D container starts at 480px tall and can be resized using its corner.
Grid Plan does not ship css. To customize the styling of the menu and inventory, target the following css classes:
.grid-plan-main {
}
.grid-plan-menu {
}
.grid-plan-menu__summary {
} /* If the menu accordion prop is true */
.grid-plan-menu__body {
} /* If the menu accordion prop is true */
.grid-plan-inventory {
}
.grid-plan-inventory__summary {
}
.grid-plan-inventory__body {
}
.grid-plan-grid {
}
.grid-plan-grid-3d {
}
.grid-plan-grid-3d-label {
}A set of icons is provided by grid-plan. These icons are adapted from the great Tabler icons open source icon library.
Icons are used in availableTypes:
const availableTypes = ref([
{
color: '#6376DD',
description: 'router',
icon: 'router',
typeId: 1,
iconColor: '#FFFFFF'
},
{...}
])| Icon name |
|---|
| airConditioning |
| alertTriangle |
| analyze |
| archive |
| armchair |
| award |
| bath |
| battery |
| bed |
| bell |
| bellSchool |
| bolt |
| boltOff |
| books |
| bulb |
| bulfOff |
| burger |
| calculator |
| camera |
| cctv |
| chefHat |
| circleKey |
| circuitCapacitor |
| circuitCell |
| circuitGround |
| circuitSwitchClosed |
| circuitSwitchOpen |
| clock |
| cloud |
| cloudComputing |
| coffee |
| cpu |
| cricuitLoop |
| database |
| deviceDesktop |
| deviceDesktopOff |
| deviceDualScreen |
| deviceImac |
| deviceImacOff |
| deviceLaptop |
| deviceLaptopOff |
| deviceTablet |
| deviceTabletOff |
| deviceTv |
| deviceTvOff |
| deviceUsb |
| devicesPc |
| devicesPcOff |
| disabled |
| door |
| doorEnter |
| doorExit |
| elevator |
| elevatorOff |
| escalator |
| escalatorDown |
| escalatorUp |
| fingerprint |
| firstAidKit |
| folder |
| folders |
| headphones |
| headset |
| hexagon |
| home |
| key |
| keyboard |
| leaf |
| lock |
| lockAccess |
| man |
| microphone |
| microscope |
| network |
| networkOff |
| package |
| packages |
| paperclip |
| phone |
| plant |
| plugConnected |
| power |
| printer |
| printerOff |
| prism |
| propeller |
| propellerOff |
| reportAnalytics |
| robot |
| router |
| salad |
| server |
| serverBolt |
| serverCog |
| serverOff |
| shredder |
| sofa |
| solarPanel |
| soup |
| squareKey |
| stack |
| toilet |
| toiletPaper |
| toolsKitchen |
| trafficCone |
| trash |
| trolley |
| volume |
| wall |
| washMachine |
| wave |
| wifi |
| windMill |
| windmillOff |
| window |
| world |
The standalone demo lives in playground/ and consumes
the current package through its built dist exports. Install workspace dependencies, then run pnpm run dev from the root. This builds and watches the
library alongside the playground. Use pnpm run build:playground to build the
demo, or pnpm run test:playground for its tests.
The package also exports defaultConfig, which the playground uses to initialize
its configuration controls:
import { GridPlan, defaultConfig } from "grid-plan";
const config = { ...defaultConfig };The package includes generated declarations at dist/types/index.d.ts.
import { GridPlan, defaultConfig } from "grid-plan";
import type {
GridPlanConfig,
GridPlanItem,
GridPlanItemType,
GridPlanTooltipSlotProps,
} from "grid-plan";
const config: GridPlanConfig = { ...defaultConfig, showTooltip: true };
// In a Vue script setup:
// const plan = ref<InstanceType<typeof GridPlan> | null>(null);Keyboard navigation is available in both grid views. Tab to the grid, then use
Right/Down to focus the next item or Left/Up to focus the previous item, wrapping
through the current item order. Enter selects the focused item; Escape clears
focus and selection. In readonly mode, only arrow navigation is enabled.
Focused items show their information, including the tooltip slot when
showTooltip is enabled. Leaving the grid clears keyboard focus.
The tooltip exposes data-position="top|bottom|left|right" for custom CSS.
It reflects the actual placement after boundary adjustments, so styles follow
any automatic flip. For example:
.grid-plan-tooltip[data-position="bottom"] {
border-top: 2px solid currentColor;
}The theme config option accepts "dark" (default, preserving the original
palette) or "light". Both the 2D and 3D views update when it changes.
Explicit configuration values override theme defaults; item type colors stay
under your control.
<GridPlan :config="{ theme: 'light', gridHighlightColor: '#0d9488' }" />Pass only the settings you want to override. Spreading defaultConfig into a
light config also explicitly overrides its palette with the dark defaults.
For a complete configuration with the chosen theme applied, use
resolveConfig({ theme: 'light' }), exported by grid-plan.
Call hintItem(item) on a GridPlan component ref with the same item object accepted
by focusItem. It shows the item's hover feedback in the 2D and 3D views without
selecting it or emitting selection events, including in readonly mode. Call
hintItem(null) to clear the hint. Pointer hover takes priority over the hint.
planRef.value.hintItem(planRef.value.getItems()[0]);
planRef.value.hintItem(null);Existing GridPlan props, ref methods, and slots remain available. The
#availableType and #inventory slots now render the standalone controls internally;
without these slots, no internal menu or inventory is rendered.
Remove these grid config properties:
| v3 config | v4 replacement |
|---|---|
showMenu, showInventory |
Omit the corresponding slot, or use v-if on standalone controls |
accordionMenuTitle, inventoryTitle |
title prop on GridPlanMenu / GridPlanInventory |
useAccordionMenu |
accordion prop on GridPlanMenu |
For external controls, create a shared controller with useGridPlan() and pass
it as :plan to the grid, menu, and inventory. Use their default slots for custom
content. See Shared controller and external controls.
Readonly mode now also blocks deletion and type selection through controller
methods. Item x and y remain numeric; display-coordinate helpers are optional.
focusItem(item) now emits select when selecting an item and unselect when
toggling it off. Review existing event handlers to avoid handling the same action
twice if you also handle it directly where focusItem() is called.


