# Pixel stars
> Five pixel stars that fill like liquid as you hover; picking one pops it with sparks and rolls the label.
- Element: `<px-rating>`
- React: `import { PxRating } from "@/components/lumesec/px-rating"`
- Collection: Pixel Lab (https://elements.lumesec.ai/components/pixel-lab)
- Registry item: https://elements.lumesec.ai/r/px-rating.json
- Page: https://elements.lumesec.ai/components/pixel-lab/rating



Live preview: https://elements.lumesec.ai/view/px-rating

```html
<script type="module" src="https://elements.lumesec.ai/cdn/px-rating.js"></script>

<px-rating></px-rating>
```

## Installation

```bash
npx shadcn@latest add @lumesec/px-rating
```

First time with the @lumesec registry? Register it once, or install by URL:

```bash
npx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json
npx shadcn@latest add https://elements.lumesec.ai/r/px-rating.json
```

## Usage

React:

```tsx
import { PxRating } from "@/components/lumesec/px-rating";

export function Example() {
  return (
    <PxRating />
  );
}
```

HTML:

```html
<script type="module" src="https://elements.lumesec.ai/cdn/px-rating.js"></script>

<px-rating></px-rating>
```

## Behaviour

Stars fill like liquid as you hover, column by column with a wave at the front. Picking one pops it with sparks and rolls the label.

## API reference

### Events

Events bubble and cross the shadow boundary unless the description says otherwise.

| Event    | React prop | Detail              | Description                                                                 |
| -------- | ---------- | ------------------- | --------------------------------------------------------------------------- |
| `change` | `onChange` | `{ value: number }` | Fires when a rating from 1 to 5 is picked by pointer, keyboard or `pick()`. |

### Methods

Call them on the element, for example through a React ref.

| Method                | Description                                                                      |
| --------------------- | -------------------------------------------------------------------------------- |
| `pick(value: number)` | Sets the rating to 1 to 5, updates the label and ARIA values and fires `change`. |

### Properties

| Property | Type     | Description                                                                                                          |
| -------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `value`  | `number` | Current rating, `0` until one is picked. Writing it directly does not update the label or ARIA values; use `pick()`. |

## Keyboard

| Keys                  | Action                                             |
| --------------------- | -------------------------------------------------- |
| ArrowRight / ArrowUp  | Raise the rating by one star.                      |
| ArrowLeft / ArrowDown | Lower the rating by one star, to a minimum of one. |
| 1 to 5                | Set that rating directly.                          |

## Accessibility

* The star canvas is focusable with `role="slider"`, `aria-label="Rating"`, `aria-valuemin="0"` and `aria-valuemax="5"`.
* `aria-valuenow` and `aria-valuetext` (for example "4 of 5, Good") update when a rating is picked.
* The word label is an `aria-live="polite"` region; it also changes while the pointer hovers.
* Reduced motion: stars fill at once without the wave and sparks are skipped; the picked star still pops briefly.

## Theming

The element reads your shadcn theme tokens through its shadow root, so light and dark follow your theme. The accent comes from `--lumesec`. See [Theming](/docs/theming).

This component reads `--foreground`, `--lumesec` and `--muted-foreground`.

To restyle only LumeSec elements, set the matching `--ui-*` overrides: `--ui-accent`, `--ui-fg` and `--ui-muted`.

## Notes

* The prompt "How was this answer?" and the labels Terrible, Not great, Okay, Good and Loved it are fixed.
* The star canvas is a fixed 236 by 52px.