Unit Field

Storybook GitHub

<script setup lang="ts">
  // @ts-nocheck -- demo SFC; the library component's dist types are incomplete for these props
import { ref } from "vue";
import MtUnitField from "@shopware-ag/meteor-component-library/MtUnitField";

const value = ref<number | null>(null);
const unit = ref("m");
</script>

<template>
  <mt-unit-field
    v-model="value"
    v-model:default-unit="unit"
    label="Length"
    measurement-type="length"
  />
</template>

Usage

Unit Field is a numeric input combined with a unit selector for measurements such as lengths, weights, or other values that may switch between compatible units. Use it when users should enter a value together with a measurement unit, and when unit conversion should happen as part of the input flow.

import { MtUnitField } from "@shopware-ag/meteor-component-library";

Examples

Disabled

<script setup lang="ts">
  // @ts-nocheck -- demo SFC; the library component's dist types are incomplete for these props
import { ref } from "vue";
import MtUnitField from "@shopware-ag/meteor-component-library/MtUnitField";

const value = ref<number | null>(12);
const unit = ref("m");
</script>

<template>
  <mt-unit-field
    v-model="value"
    v-model:default-unit="unit"
    label="Length"
    measurement-type="length"
    disabled
  />
</template>

Error

<script setup lang="ts">
  // @ts-nocheck -- demo SFC; the library component's dist types are incomplete for these props
import { ref } from "vue";
import MtUnitField from "@shopware-ag/meteor-component-library/MtUnitField";

const value = ref<number | null>(null);
const unit = ref("m");
</script>

<template>
  <mt-unit-field
    v-model="value"
    v-model:default-unit="unit"
    label="Length"
    measurement-type="length"
    :error="{ detail: 'Enter a length.' }"
  />
</template>

API reference

Props

Prop	Type	Default
`default-unit` *	"B" \| "C" \| "mm" \| "min" \| "cm" \| "m" \| "km" \| "in" \| "ft-us" \| "ft" \| "yd" \| "mi" \| "mm2" \| "cm2" \| "m2" \| "ha" \| "km2" \| "in2" \| "ft2" \| "ac" \| "mi2" \| "mcg" \| "mg" \| "g" \| "kg" \| "oz" \| "lb" \| "mt" \| "t" \| "mm3" \| "cm3" \| "ml" \| "l" \| "kl" \| "m3" \| "km3" \| "tsp" \| "Tbs" \| "in3" \| "fl-oz" \| "cup" \| "pnt" \| "qt" \| "gal" \| "ft3" \| "yd3" \| "mm3/s" \| "cm3/s" \| "ml/s" \| "cl/s" \| "dl/s" \| "l/s" \| "l/min" \| "l/h" \| "kl/s" \| "kl/min" \| "kl/h" \| "m3/s" \| "m3/min" \| "m3/h" \| "km3/s" \| "tsp/s" \| "Tbs/s" \| "in3/s" \| "in3/min" \| "in3/h" \| "fl-oz/s" \| "fl-oz/min" \| "fl-oz/h" \| "cup/s" \| "pnt/s" \| "pnt/min" \| "pnt/h" \| "qt/s" \| "gal/s" \| "gal/min" \| "gal/h" \| "ft3/s" \| "ft3/min" \| "ft3/h" \| "yd3/s" \| "yd3/min" \| "yd3/h" \| "F" \| "K" \| "R" \| "ns" \| "mu" \| "ms" \| "s" \| "h" \| "d" \| "week" \| "month" \| "year" \| "Hz" \| "mHz" \| "kHz" \| "MHz" \| "GHz" \| "THz" \| "rpm" \| "deg/s" \| "rad/s" \| "m/s" \| "km/h" \| "m/h" \| "knot" \| "ft/s" \| "s/m" \| "min/km" \| "s/ft" \| "min/mi" \| "Pa" \| "hPa" \| "kPa" \| "MPa" \| "bar" \| "torr" \| "psi" \| "ksi" \| "b" \| "Kb" \| "Mb" \| "Gb" \| "Tb" \| "KB" \| "MB" \| "GB" \| "TB" \| "lx" \| "ft-cd" \| "ppm" \| "ppb" \| "ppt" \| "ppq" \| "V" \| "mV" \| "kV" \| "A" \| "mA" \| "kA" \| "W" \| "mW" \| "kW" \| "MW" \| "GW" \| "VA" \| "mVA" \| "kVA" \| "MVA" \| "GVA" \| "VAR" \| "mVAR" \| "kVAR" \| "MVAR" \| "GVAR" \| "Wh" \| "mWh" \| "kWh" \| "MWh" \| "GWh" \| "J" \| "kJ" \| "VARh" \| "mVARh" \| "kVARh" \| "MVARh" \| "GVARH" \| "deg" \| "rad" \| "grad" \| "arcmin" \| "arcsec"	`"mm"`
`measurement-type`	`"length" \| "mass"`	`"length"`
`model-value`	`number`	`undefined`
`placeholder`	`string`
`number-type`	`"float" \| "int"`
`step`	`number`	`1`
`min`	`number`
`max`	`number`
`digits`	`number`
`fill-digits`	`false \| true`
`allow-empty`	`false \| true`
`number-align-end`	`false \| true`
`label`	`string`
`error`	`object`
`disabled`	`false \| true`
`required`	`false \| true`
`name`	`string`
`size`	`"default" \| "small"`
`help-text`	`string`
`is-inherited`	`false \| true`
`is-inheritance-field`	`false \| true`
`disable-inheritance-toggle`	`false \| true`
`copyable`	`false \| true`
`copyable-tooltip`	`false \| true`
`z-index`	`number \| null`	`null`

Events

Event	Payload
`update:modelValue`	`[value: number \| undefined]`
`inheritance-remove`	`[]`
`inheritance-restore`	`[]`
`update:defaultUnit`	`[value: convert.Unit]`
`update:measurementType`	`[value: "length" \| "mass"]`

Best practices

Use a clear label that explains what is being measured.
Set a sensible defaultUnit for the most common case.
Choose the right measurementType so the available units match the use case.

Don't

Do not use Unit Field when the unit is fixed and never changes.
Do not use it for non-measurement values such as counts or identifiers.
Do not hide the meaning of the measurement behind a vague label.

Behavior

Unit Field combines Number Field behavior with a unit selector.
Changing the selected unit can convert the current value to keep the measurement consistent.
measurementType controls which units are available, and defaultUnit controls the current selection.

Accessibility

Always provide a visible label so users understand what the measurement refers to.
Make sure unit changes remain understandable, especially when the displayed numeric value updates after conversion.
Use help text when users need guidance about accepted ranges or preferred units.

Number Field: when the value is numeric and the unit is fixed or communicated elsewhere.

Edit this pageorReport an issue

Tooltip

A floating layer of brief supporting information shown when users hover or focus a trigger element.

URL Field

A single-line input for entering and normalizing a web address.