# Circle Input

> A segmented character input rendered as a row of circular cells that auto-types words, collapses to a single circle, and spreads back out.

<demo-circle-input>



</demo-circle-input>

## Installation

```bash
npx shadcn-vue@latest add "https://nxui.geoql.in/r/circle-input.json"
```

## Usage

```vue
<script setup lang="ts">
  import CircleInput from '~/components/ui/circle-input/CircleInput.vue';
</script>

<template>
  <CircleInput :words="['HELLO', 'WORLD']" :length="5" />
</template>
```

With `words` set and `autoplay` on (default), the field types each word one
letter per circle, holds, then collapses the row into a single center circle
and spreads back out to loop. Focus the field to take over with real keyboard
input — autoplay pauses while focused and resumes on blur. Use `v-model` to
read or drive the value directly:

```vue
<template>
  <CircleInput v-model="code" :words="[]" :length="6" :autoplay="false" />
</template>
```

## Props

<table>
<thead>
  <tr>
    <th>
      Prop
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        length
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        5
      </code>
    </td>
    
    <td>
      Number of character cells
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        model-value
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        ''
      </code>
    </td>
    
    <td>
      Two-way bound value (uppercased, clamped to <code>
        length
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        words
      </code>
    </td>
    
    <td>
      <code>
        string[]
      </code>
    </td>
    
    <td>
      <code>
        ['HELLO', 'WORLD']
      </code>
    </td>
    
    <td>
      Words the autoplay loop types. Empty disables autoplay
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        autoplay
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Auto-type the <code>
        words
      </code>
      
       in a loop
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type-speed
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        260
      </code>
    </td>
    
    <td>
      Per-character type delay, in ms
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        hold-duration
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        1100
      </code>
    </td>
    
    <td>
      How long a completed word rests before collapsing, in ms
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        accent
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        '#22d3ee'
      </code>
    </td>
    
    <td>
      Accent color for the active ring + caret
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        size
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        72
      </code>
    </td>
    
    <td>
      Diameter of each circular cell, in px
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        gap
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        20
      </code>
    </td>
    
    <td>
      Gap between cells, in px
    </td>
  </tr>
</tbody>
</table>

## Events

<table>
<thead>
  <tr>
    <th>
      Event
    </th>
    
    <th>
      Payload
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        update:modelValue
      </code>
    </td>
    
    <td>
      <code>
        value: string
      </code>
    </td>
    
    <td>
      Fired as the value changes (v-model)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        complete
      </code>
    </td>
    
    <td>
      <code>
        word: string
      </code>
    </td>
    
    <td>
      Fired when an autoplay word finishes typing
    </td>
  </tr>
</tbody>
</table>

## Credits

Inspired by the circular typing interaction by [@hours](https://x.com/hours).