---
outline: deep
---

# Rating

Ratings are used to display or collect a score on a star-based scale. Commonly used for product reviews, feedback forms, and satisfaction surveys.

**`<l-rating>`** — Custom Element · Shadow DOM

## Options

### Basic

Displays a read-only fractional rating.

```html
<l-rating value="3.7"></l-rating>
```

### Editable

Add `edit-mode` to allow user input via radio buttons.

```html
<l-rating
  name="score"
  value="3"
  edit-mode
></l-rating>
```

### Labels

Pipe-separated `labels` attribute shows a text label for each star value.

```html
<l-rating
  name="score"
  value="2"
  edit-mode
  labels="Terrible|Poor|Average|Good|Excellent"
></l-rating>
```

### Length

Set `length` to change the number of stars. Defaults to `5`.

```html
<div class="flex flex-col gap-4">
  <l-rating
    value="2"
    length="3"
  ></l-rating>
  <l-rating value="4.2"></l-rating>
  <l-rating
    value="7.3"
    length="10"
  ></l-rating>
</div>
```

### Sizes

Override `--icon-size`.

```html
<div class="flex flex-col gap-4">
  <l-rating
    value="3.4"
    style="--icon-size: 12px"
  ></l-rating>
  <l-rating
    value="3.4"
    style="--icon-size: 16px"
  ></l-rating>
  <l-rating value="3.4"></l-rating>
  <l-rating
    value="3.4"
    style="--icon-size: 32px"
  ></l-rating>
</div>
```

### Custom colors

Override `--active-color` and `--inactive-color`.

```html
<div class="flex flex-col gap-4">
  <l-rating
    value="4"
    style="--active-color: tomato"
  ></l-rating>
  <l-rating
    value="3.2"
    style="--active-color: oklch(0.65 0.24 280); --inactive-color: oklch(0.9 0.05 280)"
  ></l-rating>
</div>
```

### Disabled

Native `disabled` attribute.

```html
<div class="flex flex-col gap-4">
  <l-rating
    value="3.8"
    disabled
  ></l-rating>
  <l-rating
    name="score"
    value="3"
    edit-mode
    disabled
  ></l-rating>
</div>
```

### Custom shape

Override `--icon` with any SVG `url()`.

```html
<l-rating
  value="4.1"
  style="
    --icon: url('data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 24 24%22><path d=%22M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54L12 21.35z%22/></svg>');
    --active-color: tomato;
  "
></l-rating>
```

### Value-based shapes

Assign the `getIcon` property — a function returning a CSS `url()` per position.

```html
<l-rating
  class="emoji-rating"
  value="3"
  edit-mode
  style="
    --icon-size: 24px;
    --active-color: oklch(0.75 0.18 60);
    --inactive-color: oklch(0.9 0.02 60);
  "
></l-rating>
```

## Examples

### Social proof

Avatar group + star rating as a trust badge.

```html
<div class="flex items-center gap-3">
  <div class="l-avatar-group">
    <l-avatar
      style="--appearance: circle; --color: var(--color-purple-200)"
      name="Alice Martin"
      size="sm"
    ></l-avatar>
    <l-avatar
      style="--appearance: circle; --color: var(--color-orange-200)"
      name="Marc Dupont"
      size="sm"
    ></l-avatar>
    <l-avatar
      style="--appearance: circle; --color: var(--color-green-200)"
      name="Sophie Lemaire"
      size="sm"
    ></l-avatar>
    <l-avatar
      style="--appearance: circle; --color: var(--color-blue-200)"
      name="Lucas Bernard"
      size="sm"
    ></l-avatar>
  </div>
  <div>
    <div class="flex items-center gap-1">
      <l-rating
        value="5"
        style="
          --icon-size: 16px;
          --active-color: var(--color-amber-400);
          --icon: url('data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 20 20%22><path d=%22M9.049 2.927c.3-.921 1.603-.921 1.902 0l1.07 3.292a1 1 0 00.95.69h3.462c.969 0 1.371 1.24.588 1.81l-2.8 2.034a1 1 0 00-.364 1.118l1.07 3.292c.3.921-.755 1.688-1.54 1.118l-2.8-2.034a1 1 0 00-1.175 0l-2.8 2.034c-.784.57-1.838-.197-1.539-1.118l1.07-3.292a1 1 0 00-.364-1.118L2.98 8.72c-.783-.57-.38-1.81.588-1.81h3.461a1 1 0 00.951-.69l1.07-3.292z%22/></svg>');
        "
      ></l-rating>
    </div>
    <p
      class="text-sm"
      style="color: var(--l-color-text-tertiary)"
    >
      Déjà <strong style="color: var(--l-color-text-primary)">50+</strong> profils audités
    </p>
  </div>
</div>
```

## Accessibility

### Criteria

- **Role** — In edit mode, uses native `<input type="radio">` elements — built-in semantics
- **Accessible name** — Provide an associated label via `<label>` or `aria-label` when in edit mode
- **Non-text contrast** — Star colors must meet non-text contrast ratio against the background
- **Focus** — Focus ring shown around the rating group via `:focus-within`

### Rules

- Wrap editable ratings with a visible `<label>` or provide `aria-label` on the host element
- In read-only mode, add `aria-label` describing the rating (e.g., `aria-label="3.5 out of 5 stars"`)

### Keyboard interactions

- `Tab` — Moves focus into and out of the rating group
- `ArrowLeft / ArrowRight` — Moves between radio options (native radio group behavior)
- `Space` — Selects the focused radio option

## API reference

### Importing

```js
import 'luxen-ui/rating';
```

### Attributes & Properties

- **edit-mode**: `boolean` (default: `false`)
- **labels**: `string[]` (default: `[]`)
- **value**: `number` (default: `0`)
- **length**: `number` (default: `5`)
- **getIcon**: `(value: number) => string | undefined` — Optional callback returning a CSS `url()` string for a given position (1-based).

### Methods

- **edit-mode**: `boolean` (default: `false`)
- **labels**: `string[]` (default: `[]`)
- **value**: `number` (default: `0`)
- **length**: `number` (default: `5`)
- **getIcon**: `(value: number) => string | undefined` — Optional callback returning a CSS `url()` string for a given position (1-based).

### Events

- **change** — Emitted when the rating value changes in edit mode. Bubbles. Properties: `name: string`, `value: string`, `checked: boolean`, `sourceEvent: Event`.

### CSS Parts

- `label` — The label element shown in edit mode.

### CSS custom properties

- `--icon-size` (default: `20px`) — The size of each icon.
- `--active-color` (default: `gold`) — The fill color for rated icons.
- `--inactive-color` (default: `#ddd`) — The fill color for empty icons.
- `--spacing` (default: `0px`) — The spacing between icons.
- `--icon` — Custom SVG shape as a `url()`. Defaults to a 5-pointed star.