# Rating

> One star, the average score and an optional compact count ("4.8 · 2.1K workspaces"), with built-in English and Arabic screen reader text.

Source: https://docs.nasaqui.com/components/rating

## Install

```bash
npx shadcn@latest add https://docs.nasaqui.com/r/rating.json
```

Shows an average score as a single star, the number, and optionally how many people rated or use the thing:
"★ 4.8 · 2.1K workspaces". It is one star, not five, because a row of part-filled stars is hard to read at small
sizes and says nothing the number does not. It is read-only.

## When to use

- A store listing, product card or app detail header.
- An average score with an optional count.

## When not to use

- Collecting a rating from the user: build it with buttons or a radio group; `Rating` is display only.
- A status or state: use [`Status`](https://docs.nasaqui.com/components/status).
- A label such as "New" or "Pro": use [`Badge`](https://docs.nasaqui.com/components/badge).

## Import

```tsx
import { Rating, type RatingProps } from "@fadymondy/nasaq/web";
// inside this monorepo: "@nasaq/web"
```

## Quick start

```tsx
import { Rating } from "@fadymondy/nasaq/web";

export function AppRating() {
  return <Rating value={4.8} count={2140} countLabel="workspaces" />;
}
```

## Anatomy

```
Rating                  data-slot="rating"   <span>
├─ sr-only text         full sentence for screen readers
├─ star                 lucide Star, aria-hidden
├─ score                <bdi>, one decimal
└─ count (optional)     "·", <bdi> compact count, countLabel; aria-hidden
```

## API

### `Rating`

`RatingProps extends Omit<ComponentProps<"span">, "children">`. Remaining props go to the outer `<span>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | required | Average score, for example `4.8`. Always shown with one decimal. |
| `max?` | `number` | `5` | Top of the scale. Used in the screen reader text only ("out of 5"). |
| `count?` | `number` | none | How many people or workspaces rated or use it. Shown compact: `2.1K`. Omit to hide. |
| `countLabel?` | `string` | none | What `count` counts: "workspaces", "reviews". Localise it. |
| `className?` | `string` | none | Merged onto the outer span. |

## Examples

### Score only

```tsx
import { Rating } from "@fadymondy/nasaq/web";

export function Score() {
  return <Rating value={4.6} />;
}
```

### Arabic listing

```tsx
import { NasaqProvider, Rating } from "@fadymondy/nasaq/web";

export function ArabicRating() {
  return (
    <NasaqProvider locale="ar" dir="rtl">
      <Rating value={4.8} count={2140} countLabel="مساحة عمل" />
    </NasaqProvider>
  );
}
```

## Accessibility

- A `sr-only` sentence carries the meaning: "Rated 4.8 out of 5, 2.1K workspaces". The visible star, score and
  count are `aria-hidden` so they are not read twice.
- Without a `NasaqProvider` the sentence is English. With an `ar` locale it reads in Arabic ("التقييم 4.8 من 5").
- No keyboard interaction; it is not focusable.
- Localise `countLabel` yourself.

## RTL & i18n

- Layout uses `inline-flex` and logical spacing (`me-1.5`), so the star stays on the inline start in both
  directions.
- The score and count are wrapped in `<bdi>`, so digits keep their order inside Arabic text.
- Numbers go through the Nasaq number formatter (`useFormatNumber`), so the numeral set and compact notation
  follow the active locale.
- Built-in strings: the screen reader sentence in English and Arabic. `countLabel` is yours.

## Styling & tokens

- Tokens: `text-nq-accent` (star, filled), `text-muted-foreground` (count), `text-foreground` (score), `text-caption`.
- Target with `[data-slot=rating]`.
- Extend with `className`. The count truncates when space is tight.

## Do / Don't

- **Do** pass a `countLabel` when you pass `count`, so the number means something.
- **Do** keep the star single; it reads at every size.
- **Don't** use it as an input.
- **Don't** show a score without saying what it averages when it is not obvious.

## Related

- [Price](https://docs.nasaqui.com/components/price) · [ProductCard](https://docs.nasaqui.com/components/product-card) · [Badge](https://docs.nasaqui.com/components/badge)

## Lab

https://docs.nasaqui.com/?path=/docs/components-storefront-rating--docs

## Code

### React

```tsx
import { Rating } from "@fadymondy/nasaq/web";

export function AppRating() {
  return <Rating value={4.8} count={2140} countLabel="workspaces" />;
}
```

### shadcn

```tsx
import { Rating } from "@/components/ui/rating";

export function AppRating() {
  return <Rating value={4.8} count={2140} countLabel="workspaces" />;
}
```

### Vue

```vue
<script setup lang="ts">
import { NqRating } from "@fadymondy/nasaq/vue";
</script>

<template>
  <NqRating :value="4.8" :count="2140" count-label="workspaces" />
</template>
```

### Blade

```blade
<x-nq::rating :value="4.8" :count="2140" count-label="workspaces" />
```

### HTML + Alpine

```html
<span data-slot="rating" class="inline-flex items-center gap-1.5 text-caption text-muted-foreground">
    <span class="sr-only">Rated 4.8 out of 5, 2.1K workspaces</span>
    <svg aria-hidden="true" class="size-3.5 shrink-0 fill-nq-accent text-nq-accent" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
  <path d="M11.525 2.295a.53.53 0 0 1 .95 0l2.31 4.679a2.123 2.123 0 0 0 1.595 1.16l5.166.756a.53.53 0 0 1 .294.904l-3.736 3.638a2.123 2.123 0 0 0-.611 1.878l.882 5.14a.53.53 0 0 1-.771.56l-4.618-2.428a2.122 2.122 0 0 0-1.973 0L6.396 21.01a.53.53 0 0 1-.77-.56l.881-5.139a2.122 2.122 0 0 0-.611-1.879L2.16 9.795a.53.53 0 0 1 .294-.906l5.165-.755a2.122 2.122 0 0 0 1.597-1.16z"/>
</svg>    <bdi aria-hidden="true" class="tabular-nums text-foreground">4.8</bdi>
            <span aria-hidden="true" class="truncate">
            <span class="me-1.5">·</span>
            <bdi class="tabular-nums">2.1K</bdi> workspaces
        </span>
    </span>
```