> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/lwc-components/core-components/counter.md).

# 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.

```html
<!-- 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>
```

```js
// 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.

```html
<!-- 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.                        |

### 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 <support@avonni.app> for assistance.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.avonnicomponents.com/lwc-components/core-components/counter.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.