---
title: useCounter
description: "`useCounter` is a custom hook that returns the current counter value."
links:
  - source: https://github.com/yamada-ui/yamada-ui/tree/main/packages/react/src/hooks/use-counter
---

```tsx
const { value, increment, decrement, reset } = useCounter({
  defaultValue: 10,
})

return (
  <VStack>
    <Text>Count: {value}</Text>
    <ButtonGroup.Root>
      <ButtonGroup.Item
        colorScheme="success"
        variant="subtle"
        onClick={() => increment()}
      >
        + 1
      </ButtonGroup.Item>
      <ButtonGroup.Item
        colorScheme="danger"
        variant="subtle"
        onClick={() => decrement()}
      >
        - 1
      </ButtonGroup.Item>
      <ButtonGroup.Item onClick={reset}>Reset</ButtonGroup.Item>
    </ButtonGroup.Root>
  </VStack>
)
```

## Usage

```tsx
import { useCounter } from "@yamada-ui/react"
```

```tsx
import { useCounter } from "@/components/ui"
```

```tsx
import { useCounter } from "@workspaces/ui"
```

```tsx
const { value, valueAsNumber, update, increment, decrement, reset, cast, out } =
  useCounter()
```

### Set Default Value

To set a default value, pass a number or string to `defaultValue`.

```tsx
const { value, increment, decrement, reset } = useCounter({
  defaultValue: 10,
})

return (
  <VStack>
    <Text>Count: {value}</Text>
    <ButtonGroup.Root>
      <ButtonGroup.Item
        colorScheme="success"
        variant="subtle"
        onClick={() => increment()}
      >
        + 1
      </ButtonGroup.Item>
      <ButtonGroup.Item
        colorScheme="danger"
        variant="subtle"
        onClick={() => decrement()}
      >
        - 1
      </ButtonGroup.Item>
      <ButtonGroup.Item onClick={reset}>Reset</ButtonGroup.Item>
    </ButtonGroup.Root>
  </VStack>
)
```

### Set Min And Max Values

To set minimum and maximum values, set `min` or `max` to a number.

```tsx
const { value, increment, decrement, min, max, reset } = useCounter({
  defaultValue: 5,
  min: 0,
  max: 10,
})

return (
  <VStack>
    <Text>Count: {value}</Text>
    <ButtonGroup.Root>
      <ButtonGroup.Item
        colorScheme="success"
        variant="subtle"
        onClick={() => increment()}
        disabled={max}
      >
        + 1
      </ButtonGroup.Item>
      <ButtonGroup.Item
        colorScheme="danger"
        variant="subtle"
        onClick={() => decrement()}
        disabled={min}
      >
        - 1
      </ButtonGroup.Item>
      <ButtonGroup.Item onClick={reset}>Reset</ButtonGroup.Item>
    </ButtonGroup.Root>
  </VStack>
)
```

### Set Step Value

To set a step value, pass a number to `step`.

```tsx
const { value, increment, decrement, reset } = useCounter({
  defaultValue: 0,
  step: 5,
})

return (
  <VStack>
    <Text>Count: {value}</Text>
    <ButtonGroup.Root>
      <ButtonGroup.Item
        colorScheme="success"
        variant="subtle"
        onClick={() => increment()}
      >
        + 5
      </ButtonGroup.Item>
      <ButtonGroup.Item
        colorScheme="danger"
        variant="subtle"
        onClick={() => decrement()}
      >
        - 5
      </ButtonGroup.Item>
      <ButtonGroup.Item onClick={reset}>Reset</ButtonGroup.Item>
    </ButtonGroup.Root>
  </VStack>
)
```

```tsx
const { value, increment, decrement } = useCounter({
  defaultValue: 0,
})

return (
  <VStack>
    <Text>Count: {value}</Text>
    <ButtonGroup.Root colorScheme="success" variant="subtle">
      <For each={[1, 5, 10]}>
        {(step) => (
          <ButtonGroup.Item onClick={() => increment(step)}>
            + {step}
          </ButtonGroup.Item>
        )}
      </For>
    </ButtonGroup.Root>
    <ButtonGroup.Root colorScheme="danger" variant="subtle">
      <For each={[1, 5, 10]}>
        {(step) => (
          <ButtonGroup.Item onClick={() => decrement(step)}>
            - {step}
          </ButtonGroup.Item>
        )}
      </For>
    </ButtonGroup.Root>
  </VStack>
)
```

### Specify Precision

To specify precision, pass a number to `precision`.

```tsx
const { value, increment, decrement, reset } = useCounter({
  defaultValue: 5.123,
  step: 0.1,
  precision: 2,
})

return (
  <VStack>
    <Text>Count: {value}</Text>
    <ButtonGroup.Root>
      <ButtonGroup.Item
        colorScheme="success"
        variant="subtle"
        onClick={() => increment()}
      >
        + 0.1
      </ButtonGroup.Item>
      <ButtonGroup.Item
        colorScheme="danger"
        variant="subtle"
        onClick={() => decrement()}
      >
        - 0.1
      </ButtonGroup.Item>
      <ButtonGroup.Item onClick={reset}>Reset</ButtonGroup.Item>
    </ButtonGroup.Root>
  </VStack>
)
```

### Allow Out Of Range Values

To allow out of range values, set `keepWithinRange` to `false`. The `out` property is also provided to indicate whether the value is out of range.

```tsx
const { value, increment, decrement, out, reset } = useCounter({
  defaultValue: 5,
  min: 0,
  max: 10,
  keepWithinRange: false,
})

return (
  <VStack>
    <Text color={out ? "danger" : "inherit"}>
      Count: {value} {out ? "(Out Of Range)" : ""}
    </Text>
    <ButtonGroup.Root>
      <ButtonGroup.Item
        colorScheme="success"
        variant="subtle"
        onClick={() => increment()}
      >
        + 1
      </ButtonGroup.Item>
      <ButtonGroup.Item
        colorScheme="danger"
        variant="subtle"
        onClick={() => decrement()}
      >
        - 1
      </ButtonGroup.Item>
      <ButtonGroup.Item onClick={reset}>Reset</ButtonGroup.Item>
    </ButtonGroup.Root>
  </VStack>
)
```

### Cast Value

To cast value, use the `cast` function.

```tsx
const { value, setValue, cast } = useCounter({
  defaultValue: 0,
  precision: 2,
})

return (
  <Input
    placeholder="Enter a number"
    value={value}
    onChange={(e) => setValue(e.target.value)}
    onBlur={(e) => cast(e.target.value)}
  />
)
```