SignatureField

Component

Props

id is the only required prop. The pad props (modelValue, name, height, minWidth, strokeSize, showGuide, placeholder, showClearButton, clearIcon, clearAriaLabel, disabled, readOnly) work as in SignaturePad.

Usage

id

Unique id of the field. The label gets ${id}-label and labels the drawing surface.

 <template>
    <SignatureField id="signature" label="Signature" />
</template>
 

• Type: string

label

Text of the label shown above the pad.

 <template>
    <SignatureField id="signature" label="Signature" />
</template>
 

• Type: string

ariaLabel

Accessible label of the pad when there is no visible label.

 <template>
    <SignatureField id="signature" ariaLabel="Customer signature" />
</template>
 

• Type: string

helpText

Helper text shown next to the pad. It is replaced by the error message when there is one.

 <template>
    <SignatureField id="signature" helpText="Sign inside the box" />
</template>
 

• Type: string

helpTextPosition

Places the help text above or below the pad.

 <template>
    <SignatureField id="signature" helpText="Sign inside the box" :helpTextPosition="Position.TOP" />
</template>
 

• Type: Position
• Default: Position.BOTTOM

Options

required

Marks the field as required, hides the optional label and enables validator.

 <template>
    <SignatureField id="signature" required />
</template>
 

• Type: boolean
• Default: false

showOptionalLabel

Shows the optional label when the field is not required.

 <template>
    <SignatureField id="signature" label="Signature" :showOptionalLabel="false" />
</template>
 

• Type: boolean
• Default: true

optionalLabel

Overrides the optional label text. Defaults to the text from the DS config.

 <template>
    <SignatureField id="signature" label="Signature" optionalLabel="(Optional)" />
</template>
 

• Type: string

modelValue

Strokes drawn on the pad, as a list of SVG paths.

 <template>
    <SignatureField id="signature" v-model="paths" />
</template>

<script setup lang="ts">
const paths = ref<string[]>([])
</script>
 

• Type: string[]
• Default: []

name

Renders a hidden input with the JSON-serialized strokes for native form submissions.

 <template>
    <SignatureField id="signature" name="signature" />
</template>
 

• Type: string

height

Sets the height of the pad in pixels.

 <template>
    <SignatureField id="signature" :height="280" />
</template>
 

• Type: number
• Default: 200

minWidth

Sets the minimum width of the pad in pixels. Below this width the pad stops shrinking, so the container can scroll instead of squeezing the signature area.

 <template>
    <SignatureField id="signature" :minWidth="320" />
</template>
 

• Type: number
• Default: 240

strokeSize

Sets the stroke width in pixels.

 <template>
    <SignatureField id="signature" :strokeSize="4" />
</template>
 

• Type: number
• Default: 2

showGuide

Shows the dashed baseline to sign on.

 <template>
    <SignatureField id="signature" :showGuide="false" />
</template>
 

• Type: boolean
• Default: true

placeholder

Text shown over the guide while the pad is empty.

 <template>
    <SignatureField id="signature" placeholder="Sign inside the box" />
</template>
 

• Type: string
• Default: 'Sign here'

showClearButton

Shows the icon button that removes all strokes. It only appears once something has been drawn.

 <template>
    <SignatureField id="signature" :showClearButton="false" />
</template>
 

• Type: boolean
• Default: true

clearIcon

Sets the icon of the clear button.

 <template>
    <SignatureField id="signature" :clearIcon="'mdi:close'" />
</template>
 

• Type: string
• Default: 'mdi:eraser'

clearAriaLabel

Sets the accessible label (aria-label) of the clear icon button.

 <template>
    <SignatureField id="signature" clearAriaLabel="Reset signature" />
</template>
 

• Type: string
• Default: 'Clear signature'

disabled

Disables drawing and the clear button.

 <template>
    <SignatureField id="signature" disabled />
</template>
 

• Type: boolean
• Default: false

readOnly

Shows the strokes but prevents drawing or clearing.

 <template>
    <SignatureField id="signature" readOnly :modelValue="savedPaths" />
</template>
 

• Type: boolean
• Default: false

validator

Function that receives the strokes and returns an error message, or null when valid. It runs only when required is set, following the form validation mode.

 <template>
    <SignatureField
        id="signature"
        v-model="paths"
        v-model:error="error"
        required
        :validator="value => (value as string[]).length ? null : 'Signature is required'"
    />
</template>

<script setup lang="ts">
const paths = ref<string[]>([])
const error = ref('')
</script>
 

• Type: (value: unknown) => string | null
• Default: () => null

error (v-model:error)

Sets the error message of the field. This prop is bindable via v-model:error, allowing two-way syncing of the validation state. It replaces the help text and applies the error border on the pad.

 <template>
    <SignatureField id="signature" v-model:error="errorMessage" />
</template>
 

• Type: string
• Default: ''

Accessibility

The label is linked to the drawing surface through aria-labelledby. Without a visible label, set ariaLabel. See SignaturePad for the pointer-only note.

Emits

Example

 <template>
    <SignatureField id="signature" v-model="paths" @clear="console.log('cleared')" />
</template>

<script setup lang="ts">
const paths = ref<string[]>([])
</script>
 

Methods

 <template>
    <SignatureField id="signature" ref="fieldRef" v-model="paths" />
</template>

<script setup lang="ts">
const fieldRef = ref()
const paths = ref<string[]>([])

const exportImage = () => fieldRef.value.getDataUrl()
</script>