Skip to content

addUnit — Unit Conversion ​

17:43

Description ​

$u.addUnit appends a unit to a number or CSS length value and returns a string. Numbers are not converted, strings that already carry a unit are returned as-is, and space-separated values are filled in one by one; passing null as value returns auto.

Examples ​

Basic usage (passing a number) ​

Number inputs receive the config.unit (default px), including 0.

View source
vue
<template>
    <ux-cell-group :border="false">
        <ux-cell-item title="$u.addUnit(10)" :value="$u.addUnit(10)" :arrow="false" />
        <ux-cell-item title="$u.addUnit(16)" :value="$u.addUnit(16)" :arrow="false" />
        <ux-cell-item title="$u.addUnit(20)" :value="$u.addUnit(20)" :arrow="false" />
        <ux-cell-item title="$u.addUnit(0)" :value="$u.addUnit(0)" :arrow="false" :border-bottom="false" />
    </ux-cell-group>
</template>

<script setup lang="ts">
import { $u } from '@/uni_modules/uview-pro-x';
</script>

Passing a string (with an existing unit) ​

Strings that already carry a px / rpx / % / em unit are returned as-is without appending a second unit.

View source
vue
<template>
    <ux-cell-group :border="false">
        <ux-cell-item title="$u.addUnit('10px')" :value="$u.addUnit('10px')" :arrow="false" />
        <ux-cell-item title="$u.addUnit('10rpx')" :value="$u.addUnit('10rpx')" :arrow="false" />
        <ux-cell-item title="$u.addUnit('50%')" :value="$u.addUnit('50%')" :arrow="false" />
        <ux-cell-item title="$u.addUnit('2em')" :value="$u.addUnit('2em')" :arrow="false" :border-bottom="false" />
    </ux-cell-group>
</template>

<script setup lang="ts">
import { $u } from '@/uni_modules/uview-pro-x';
</script>

Special values ​

auto and empty strings are returned as-is, null returns auto, and the second argument can set the unit explicitly, as in 16, 'px'.

View source
vue
<template>
    <ux-cell-group :border="false">
        <ux-cell-item title="$u.addUnit('auto')" :value="$u.addUnit('auto')" :arrow="false" />
        <ux-cell-item title="$u.addUnit('')" :value="$u.addUnit('')" :arrow="false" />
        <ux-cell-item title="$u.addUnit(null)" :value="$u.addUnit(null)" :arrow="false" />
        <ux-cell-item title="$u.addUnit(16, 'px')" :value="$u.addUnit(16, 'px')" :arrow="false" :border-bottom="false" />
    </ux-cell-group>
</template>

<script setup lang="ts">
import { $u } from '@/uni_modules/uview-pro-x';
</script>

Multiple values (space-separated) ​

Space-separated values are filled segment by segment, while values that already carry a unit and auto stay unchanged, which suits margin / padding shorthands.

View source
vue
<template>
    <ux-cell-group :border="false">
        <ux-cell-item title="$u.addUnit('10 20')" :value="$u.addUnit('10 20')" :arrow="false" />
        <ux-cell-item title="$u.addUnit('10px 20')" :value="$u.addUnit('10px 20')" :arrow="false" />
        <ux-cell-item title="$u.addUnit('10 10px 30')" :value="$u.addUnit('10 10px 30')" :arrow="false" />
        <ux-cell-item title="$u.addUnit('auto 10')" :value="$u.addUnit('auto 10')" :arrow="false" :border-bottom="false" />
    </ux-cell-group>
</template>

<script setup lang="ts">
import { $u } from '@/uni_modules/uview-pro-x';
</script>

API ​

Parameters ​

ParameterDescriptionTypeDefaultVersion
valueThe number or string to receive a unitnumber | string | null--
unitUnit to append; null falls back to config.unit (default px)string | nullnull-

Returns ​

TypeDescription
stringThe string with the unit appended; null input returns auto, an empty string returns '', and values that already carry a unit or auto are returned as-is

Notes ​

  • Only a null unit falls back to config.unit; a null value returns auto directly and does not use config.unit.
  • Units are appended without numeric conversion; values ending with px / rpx / % / em / rem / vh / vw are kept as-is.
  • Space-separated values are handled one by one, while auto and values that already carry a unit stay unchanged.
  • Strings that are neither numeric nor unit-bearing are returned as-is.