Skip to content

Property Panels ​

Property panels in @open-pencil/vue are intentionally composable-first.

If a panel mostly needs selection-derived values and update actions, prefer composables. If a panel needs reusable array/list structure, use a headless primitive like PropertyListRoot.

Common control composables ​

For standard property sections, start with:

  • usePosition()
  • useLayout()
  • useAppearance()
  • useTypography()
  • useExport()

For list-style panels, use:

  • useFillControls()
  • useStrokeControls()
  • useEffectsControls()

Binding-aware fields ​

Compose BindableValueRoot around fields that can reference variables or external design tokens. The primitive is presentation-agnostic, but binding-aware interfaces should keep focus non-destructive:

  • Show variable identity while the field is idle; expose the resolved value in supporting UI such as a tooltip.
  • Focusing or opening the picker must not detach a binding.
  • Apply detach-on-edit, readonly-when-bound, or edit-variable only when the user actually changes the value.
  • Put explicit detach actions in the picker rather than on a destructive one-click field icon.
  • Keep binding replacement, detach-on-edit, and multi-target changes in one provider batch.

OpenPencil's app skin uses a violet variable-name pill at rest and reveals the resolved numeric value when NumberField enters editing mode. Custom editor shells can present the same headless state differently.

Example: position panel ​

vue
<script setup lang="ts">
import { MIXED } from '@open-pencil/vue/controls/node-props'
import { usePosition } from '@open-pencil/vue/controls/position'

const { panelProp, updateProp, commitProp } = usePosition()
const x = panelProp('x')
const y = panelProp('y')
const width = panelProp('width')
const height = panelProp('height')
// A multi-selection whose layers show different values shows an empty field.
const shown = (value: number | typeof MIXED) => (value === MIXED ? '' : value)
// Applied on change, so the rounded value replaces the text only once typing is done.
function set(key: 'x' | 'y' | 'width' | 'height', event: Event) {
  const value = Number((event.target as HTMLInputElement).value)
  updateProp(key, value)
  commitProp(key, value, value)
}
</script>

<template>
  <div class="grid grid-cols-2 gap-2">
    <input :value="shown(x)" @change="set('x', $event)" />
    <input :value="shown(y)" @change="set('y', $event)" />
    <input :value="shown(width)" @change="set('width', $event)" />
    <input :value="shown(height)" @change="set('height', $event)" />
  </div>
</template>

Example: fills panel ​

vue
<script setup lang="ts">
import { PropertyListRoot } from '@open-pencil/vue/primitives/PropertyList'
import { useEditorPropertyList } from '@open-pencil/vue/controls/property-list'
import { useFillControls } from '@open-pencil/vue/controls/fill'

const fillControls = useFillControls()
const fills = useEditorPropertyList('fills')
</script>

<template>
  <PropertyListRoot
    prop-key="fills"
    :items="fills.items.value"
    :mixed="fills.isMixed.value"
    @add="fills.actions.add"
    @remove="fills.actions.remove"
    v-slot="{ items, actions }"
  >
    <div v-for="(fill, index) in items" :key="index">
      {{ fill.type }}
      <button @click="actions.remove(index)">Remove</button>
    </div>

    <button @click="actions.add(fillControls.defaultFill)">Add fill</button>
  </PropertyListRoot>
</template>

Rule of thumb ​

  • use composables for direct control logic
  • use structural primitives when repeated list/tree/slot coordination is the hard part