# Star Border

> A twinkling star that travels the exact outline of any button, pill or card, trailing light and stardust.

A canvas-drawn star glides at an even pace around the real outline of a button, pill or card, with a soft fading trail. Hover or tab to it to send the star on a fast lap, and press anywhere on the border to send light racing both ways from that point.

<demo-star-border>



</demo-star-border>

## Installation

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

## Usage

```vue
<script setup lang="ts">
  import StarBorder from '~/components/ui/star-border/StarBorder.vue';
</script>

<template>
  <StarBorder
    color="#ffcf8a"
    trail-color="#ff4d2e"
    :duration="4"
    :trail-length="0.45"
    :glow="0.8"
    hover="lap"
    @click="start"
  >
    Get started
  </StarBorder>

  <!-- Render as a link with three stars and stardust -->
  <StarBorder as="a" href="/docs" :stars="3" sparkle :radius="999">
    Read the docs
  </StarBorder>
</template>
```

## Props

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

<tbody>
  <tr>
    <td>
      <code>
        as
      </code>
    </td>
    
    <td>
      <code>
        string | Component
      </code>
    </td>
    
    <td>
      <code>
        'button'
      </code>
    </td>
    
    <td>
      Element or component to render, for example <code>
        a
      </code>
      
      , <code>
        div
      </code>
      
       or <code>
        NuxtLink
      </code>
      
      . Buttons get <code>
        type="button"
      </code>
      
       by default.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        color
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      —
    </td>
    
    <td>
      Color of the star and its glow. Defaults to white on dark and ink on light.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        trail-color
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      —
    </td>
    
    <td>
      Color the trail fades into behind the star. Defaults to <code>
        color
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        duration
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        4
      </code>
    </td>
    
    <td>
      Seconds for one lap. The star keeps the same pace on any shape.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        direction
      </code>
    </td>
    
    <td>
      <code>
        'clockwise' | 'counterclockwise'
      </code>
    </td>
    
    <td>
      <code>
        'clockwise'
      </code>
    </td>
    
    <td>
      Which way the star travels.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        stars
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        1
      </code>
    </td>
    
    <td>
      Stars spaced evenly around the border, up to 6.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        trail-length
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        0.3
      </code>
    </td>
    
    <td>
      Trail length as a share of the border. Trails stretch when the star speeds up.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        thickness
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        1
      </code>
    </td>
    
    <td>
      Border width in pixels.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        radius
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        12
      </code>
    </td>
    
    <td>
      Corner radius in pixels. Values past half the height give a pill.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        glow
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        0.6
      </code>
    </td>
    
    <td>
      Bloom around the star and its trail, from 0 to 1.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sparkle
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Twinkling glint at the front of each trail that sheds fine stardust.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        hover
      </code>
    </td>
    
    <td>
      <code>
        'lap' | 'brighten' | 'reveal' | 'none'
      </code>
    </td>
    
    <td>
      <code>
        'lap'
      </code>
    </td>
    
    <td>
      Hover and keyboard-focus behaviour: a fast lap, a stronger light, or a star hidden until you hover.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        click-pulse
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Sends light racing around the border from the point you press.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        theme
      </code>
    </td>
    
    <td>
      <code>
        'dark' | 'light'
      </code>
    </td>
    
    <td>
      <code>
        'dark'
      </code>
    </td>
    
    <td>
      Picks the default surface, text, border and star colors.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        background-color
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      —
    </td>
    
    <td>
      Surface color. Follows the theme when not set.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        text-color
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      —
    </td>
    
    <td>
      Text color. Follows the theme when not set.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        border-color
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      —
    </td>
    
    <td>
      Color of the resting border the star travels on. Follows the theme when not set.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        class
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        ''
      </code>
    </td>
    
    <td>
      Extra classes for the root, for example to change padding or font. Utility classes override the base styles.
    </td>
  </tr>
</tbody>
</table>

## Slots

<table>
<thead>
  <tr>
    <th>
      Slot
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        default
      </code>
    </td>
    
    <td>
      Button content (label and icons).
    </td>
  </tr>
</tbody>
</table>

## Accessibility

- Renders a real `<button type="button">` by default, so it is focusable and fires `click` on Enter and Space. Native attributes such as `disabled`, `href` or `aria-label` pass straight through.
- Keyboard focus shows a visible outline and triggers the same hover behaviour; a keyboard click pulses from the star's position.
- The light layer is a decorative `<canvas aria-hidden="true">`.
- With `prefers-reduced-motion: reduce` the star stops travelling and hover laps and stardust are off; it rests in place with a soft glow.
- The render loop sleeps when the star is idle or the button is off screen.
- Ported from [React Bits](https://reactbits.dev/animations/star-border) by David Haz.