Counter

avonni-counter

A number input with increment and decrement controls for stepping a value up or down.

Overview

Counter is a Lightning Web Component that displays a numeric input with increment and decrement buttons, supporting number, currency, and percent formatting.

Use it in your own Lightning Web Components to capture a bounded numeric value such as a quantity, price, or rate. You control the step, min/max range, formatting type, decimal precision, and validation—all through the component's attributes.

Use Cases

• Quantities: Let users adjust an item count with stepper buttons.
• Pricing inputs: Capture a currency value with fixed decimal precision.
• Rates and ratios: Enter a percentage with a constrained range.
• Bounded values: Keep input within a min/max range automatically.
• Read-only totals: Display a computed numeric value without editing.

---

Type Guidelines

Type	Use Case
number	Counts, quantities, generic integers or decimals.
currency	Monetary values formatted per the user's locale.
percent	Rates and ratios displayed as percentages.

---

Use Case Examples

Example 1: Bounded quantity stepper

Scenario: Capture a quantity between 1 and 10 with custom button tooltips and a validation message when the maximum is exceeded.

<!-- quantityField.html -->
<template>
    <avonni-counter
        label="Quantity"
        field-level-help="Use the buttons or arrow keys to adjust the value."
        value={quantity}
        min="1"
        max="10"
        step="1"
        type="number"
        increment-button-title="Add one"
        decrement-button-title="Remove one"
        required
        message-when-range-overflow="Quantity cannot exceed 10."
        onchange={handleChange}
    ></avonni-counter>
</template>

// quantityField.js
import { LightningElement } from 'lwc';

export default class QuantityField extends LightningElement {
    quantity = 3;

    handleChange(event) {
        this.quantity = event.detail.value; // new numeric value
    }
}

Result: A stepper bounded between 1 and 10; each step fires change with the new value, and exceeding the max shows the overflow message.

Example 2: Currency input with decimals

Scenario: Capture a unit price formatted as currency with two decimal places and a half-unit step.

<!-- priceField.html -->
<template>
    <avonni-counter
        label="Unit price"
        value={unitPrice}
        min="0"
        step="0.5"
        type="currency"
        fraction-digits="2"
        variant="label-inline"
        onchange={handleChange}
    ></avonni-counter>
</template>

Result: A currency-formatted counter showing two decimals; stepping by 0.5 fires change with the updated value.

---

Specifications

Attributes

Name	Description	Type	Default	Required
access-key	Specifies a shortcut key to activate or focus an element.	String	—
aria-controls	A space-separated list of element IDs whose presence or content is controlled by the input.	String	—
aria-described-by	A space-separated list of element IDs that provide descriptive labels for the input.	String	—
aria-label	Describes the input to assistive technologies.	String	—
aria-labelled-by	A space-separated list of element IDs that provide labels for the input.	String	—
decrement-button-title	Title for the decrement button.	String	"Decrement counter"
disabled	If present, the input field is disabled and users cannot interact with it.	Boolean	false
field-level-help	Help text detailing the purpose and function of the input.	String	—
fraction-digits	Granularity of the value - number of significant decimal digits specified as a positive integer. For example, 2 formats the value to 2 digits after the decimal.	Number	"null"
increment-button-title	Title for the increment button.	String	"Increment counter"
label	Text label for the input.	String	—	Yes
max	The maximum acceptable value for the input. Constrains the incrementer to stop at the specified maximum. If the entered value is above the maximum, incrementing or decrementing will then set the value to the specified maximum.	Number	—
message-when-bad-input	Error message to be displayed when a bad input is detected.	String	—
message-when-pattern-mismatch	Error message to be displayed when a pattern mismatch is detected.	String	—
message-when-range-overflow	Error message to be displayed when a range overflow is detected.	String	—
message-when-range-underflow	Error message to be displayed when a range underflow is detected.	String	—
message-when-step-mismatch	Error message to be displayed when a step mismatch is detected.	String	—
message-when-value-missing	Error message to be displayed when the value is missing.	String	—
min	The minimum acceptable value for the input. Constrains the decrementer to stop at the specified minimum. If an entered value is below the minimum, incrementing or decrementing will then set the value to the specified minimum.	Number	—
name	Specifies the name of an input element.	String	—
read-only	If present, the input field is read-only and cannot be edited by users.	Boolean	false
required	If present, the input field must be filled out before the form is submitted.	Boolean	false
required-alternative-text	The assistive text when the required attribute is set to true.	String	"Required"
step	Amount to add or subtract from the value.	Number	1
type	Input counter type. Valid values include number, currency and percent.	String	"number"
validity	Represents the validity states that an element can be in, with respect to constraint validation.	String	—
value	Specifies the value of an input element.	Number	"null"
variant	The variant changes the appearance of an input field. Accepted variants include standard, label-inline, label-hidden, and label-stacked. This value defaults to standard, which displays the label above the field. Use label-hidden to hide the label but make it available to assistive technology. Use label-inline to horizontally align the label and input field. Use label-stacked to place the label above the input field.	String	"standard"

Methods

Name	Description	Argument Name	Argument Type	Argument Description
blur	Removes keyboard focus from the input element.
checkValidity	Checks if the input is valid.
focus	Sets focus on the input element.
reportValidity	Displays the error messages. If the input is valid, reportValidity() clears displayed error messages.
setCustomValidity	Sets a custom error message to be displayed when a form is submitted.	message	String	The string that describes the error. If message is an empty string, the error message is reset.
showHelpMessageIfInvalid	Displays error messages on invalid fields. An invalid field fails at least one constraint validation and returns false when checkValidity() is called.

Custom Events

blur

The event fired when the focus is removed from the input counter.

The blur event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

change

The event fired when the value changes.

The change event returns the following parameters.

Parameter	Type	Description
value	number	New value of the input.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

focus

The event fired when the input counter receives focus.

The focus event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

blur

The event fired when the focus is removed from the input counter.

The blur event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

change

The event fired when the value changes.

The change event returns the following parameters.

Parameter	Type	Description
value	number	New value of the input.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

focus

The event fired when the input counter receives focus.

The focus event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

Styling Hooks

CSS Variable	Type	Default
--avonni-input-counter-header-text-color	color	#3e3e3c
--avonni-input-counter-header-font-size	font	0.75rem
--avonni-input-counter-header-font-style	font	normal
--avonni-input-counter-header-font-weight	font	400

Key Considerations

• Accessibility: label is required; use variant="label-hidden" to keep it available to assistive technology while hiding it visually.
• Bounds: Entering a value outside min/max and then stepping snaps the value back to the nearest bound.
• Formatting: fraction-digits controls displayed precision; pair it with the appropriate type for currency and percent.
• Read-only: Use read-only to display a computed value without allowing edits or stepping.
• Best Practice: Set min and max to bound the value, and match type and fraction-digits to the data—e.g. currency with fraction-digits="2" for money.

---

Troubleshooting Common Issues

• Value not updating: Confirm the change handler reads event.detail.value and writes it back to the bound property.
• Decimals truncated unexpectedly: Check fraction-digits—a value of 0 rounds to a whole number.
• Buttons won't go past a number: That's min/max working as designed; widen the range if needed.
• If issues persist: Contact our support team at [email protected] for assistance.