# Rating

Die Rating Component dient zur visuellen Darstellung einer Bewertungsskala von 0 bis 5 Sternen. Sie wird häufig eingesetzt, um Bewertungen auf einen Blick verständlich zu machen.

## Overview

# Playground

Verwende `<Rating />`, um ein Rating anzubieten. Um die Barrierefreiheit zu
gewährleisten, wird in der Rating Component automatisch ein entsprechendes
ARIA-Label für die einzelnen Rating-Stufen generiert.

```tsx
import {
  Label,
  Rating,
} from "@mittwald/flow-react-components";

<Rating>
  <Label>Bewertung</Label>
</Rating>
```

---

# Sizes

Es stehen die Größen **Medium** oder **Small** zur Verfügung.

```tsx
import { Rating } from "@mittwald/flow-react-components";

<>
  <Rating defaultValue={2} aria-label="Bewertung" />
  <Rating
    size="s"
    defaultValue={2}
    aria-label="Bewertung"
  />
</>
```

---

# Readonly

Verwende `isReadOnly`, wenn du die Rating-Komponente nur zur Darstellung
verwenden möchtest.

```tsx
import { Rating } from "@mittwald/flow-react-components";

<Rating value={2} isReadOnly aria-label="Bewertung" />
```

---

# Alternative Icons

Über die Properties `iconEmpty` und `iconFilled` können benutzerdefinierte
[Icons](/04-components/content/icons/overview) gesetzt werden.

```tsx
import {
  Icon,
  Rating,
} from "@mittwald/flow-react-components";
import {
  IconLeaf,
  IconLeafFilled,
} from "@tabler/icons-react";

<Rating
  aria-label="Bewertung"
  iconEmpty={
    <Icon>
      <IconLeaf />
    </Icon>
  }
  iconFilled={
    <Icon status="success">
      <IconLeafFilled />
    </Icon>
  }
  defaultValue={2}
/>
```

---

# Kombiniere mit ...

## BigNumber

Das Rating kann mit einer
[BigNumber](/04-components/data-visualisation/big-number/overview) kombiniert
werden, um den Wert der BigNumber visuell besser einordnen zu können.

```tsx
import {
  BigNumber,
  Flex,
  Rating,
  Text,
} from "@mittwald/flow-react-components";

<Flex direction="column" gap="s" align="center">
  <BigNumber>
    <Text>80%</Text>
    <Text>Performance</Text>
  </BigNumber>
  <Rating aria-label="Performance" value={4} isReadOnly />
</Flex>
```

## AccentBox

Zur visuellen Hervorhebung kann das Rating innerhalb einer
[AccentBox](/04-components/structure/accent-box/overview) angezeigt werden.

```tsx
import {
  AccentBox,
  BigNumber,
  ColumnLayout,
  Flex,
  Rating,
  Text,
} from "@mittwald/flow-react-components";

<ColumnLayout>
  <AccentBox>
    <Flex direction="column" gap="s" align="center">
      <BigNumber>
        <Text>250 ms</Text>
        <Text>Dateioperationen</Text>
      </BigNumber>
      <Rating aria-label="Bewertung" value={4} isReadOnly />
      <Text>
        <small>Geringer Optimierungsbedarf</small>
      </Text>
    </Flex>
  </AccentBox>
  <AccentBox>
    <Flex direction="column" gap="xs" align="center">
      <BigNumber>
        <Text>100 ms</Text>
        <Text>Serveroperationen</Text>
      </BigNumber>
      <Rating aria-label="Bewertung" value={2} isReadOnly />
      <Text>
        <small>Optimierungsbedarf</small>
      </Text>
    </Flex>
  </AccentBox>
</ColumnLayout>
```


## Develop

# Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | `: 0` | The value sets the amount of filled stars. |
| `defaultValue` | `number` | `: 0` | The defaultValue sets the amount of default filled stars. |
| `size` | `"s" \| "m"` | `: "m"` | The size of the component. |
| `iconEmpty` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | An alternative icon for the empty state |
| `iconFilled` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | An alternative icon for the filled state |
| `wrapWith` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | - | - |
| `ref` | `Ref<HTMLSpanElement>` | - | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). @see [React Docs](https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom) |
| `key` | `Key` | - | - |
| `children` | `ReactNode` | - | - |
| `id` | `string` | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| `translate` | `"yes" \| "no"` | - | - |
| `className` | `ClassNameOrFunction<RadioGroupRenderProps>` | `'react-aria-RadioGroup'` | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| `style` | `StyleOrFunction<TooltipRenderProps>` | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| `render` | `DOMRenderFunction<"div", TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| `dir` | `string` | - | - |
| `lang` | `string` | - | - |
| `hidden` | `boolean` | - | - |
| `inert` | `boolean` | - | - |
| `validationBehavior` | `"native" \| "aria"` | `'native'` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
| `isDisabled` | `boolean` | - | Whether the input is disabled. |
| `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed by the user. |
| `isRequired` | `boolean` | - | Whether user input is required on the input before form submission. |
| `isInvalid` | `boolean` | - | Whether the input value is invalid. |
| `validate` | `((value: TimeValue) => true \| ValidationError)` | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead. |
| `name` | `string` | - | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| `form` | `string` | - | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). |
| `slot` | `string` | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `orientation` | `Orientation` | `'vertical'` | The axis the Radio Button(s) should align with. |

### Events

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `onClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onClickCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onAuxClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onAuxClickCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onContextMenu` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onContextMenuCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onDoubleClick` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onDoubleClickCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseDown` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseDownCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseEnter` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseLeave` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseMove` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseMoveCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseOut` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseOutCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseOver` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseOverCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseUp` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onMouseUpCapture` | `MouseEventHandler<HTMLDivElement>` | - | - |
| `onTouchCancel` | `TouchEventHandler<HTMLDivElement>` | - | - |
| `onTouchCancelCapture` | `TouchEventHandler<HTMLDivElement>` | - | - |
| `onTouchEnd` | `TouchEventHandler<HTMLDivElement>` | - | - |
| `onTouchEndCapture` | `TouchEventHandler<HTMLDivElement>` | - | - |
| `onTouchMove` | `TouchEventHandler<HTMLDivElement>` | - | - |
| `onTouchMoveCapture` | `TouchEventHandler<HTMLDivElement>` | - | - |
| `onTouchStart` | `TouchEventHandler<HTMLDivElement>` | - | - |
| `onTouchStartCapture` | `TouchEventHandler<HTMLDivElement>` | - | - |
| `onPointerDown` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerDownCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerMove` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerMoveCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerUp` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerUpCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerCancel` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerCancelCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerEnter` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerLeave` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerOver` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerOverCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerOut` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onPointerOutCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onGotPointerCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onGotPointerCaptureCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onLostPointerCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onLostPointerCaptureCapture` | `PointerEventHandler<HTMLDivElement>` | - | - |
| `onScroll` | `UIEventHandler<HTMLDivElement>` | - | - |
| `onScrollCapture` | `UIEventHandler<HTMLDivElement>` | - | - |
| `onWheel` | `WheelEventHandler<HTMLDivElement>` | - | - |
| `onWheelCapture` | `WheelEventHandler<HTMLDivElement>` | - | - |
| `onAnimationStart` | `AnimationEventHandler<HTMLDivElement>` | - | - |
| `onAnimationStartCapture` | `AnimationEventHandler<HTMLDivElement>` | - | - |
| `onAnimationEnd` | `AnimationEventHandler<HTMLDivElement>` | - | - |
| `onAnimationEndCapture` | `AnimationEventHandler<HTMLDivElement>` | - | - |
| `onAnimationIteration` | `AnimationEventHandler<HTMLDivElement>` | - | - |
| `onAnimationIterationCapture` | `AnimationEventHandler<HTMLDivElement>` | - | - |
| `onTransitionCancel` | `TransitionEventHandler<HTMLDivElement>` | - | - |
| `onTransitionCancelCapture` | `TransitionEventHandler<HTMLDivElement>` | - | - |
| `onTransitionEnd` | `TransitionEventHandler<HTMLDivElement>` | - | - |
| `onTransitionEndCapture` | `TransitionEventHandler<HTMLDivElement>` | - | - |
| `onTransitionRun` | `TransitionEventHandler<HTMLDivElement>` | - | - |
| `onTransitionRunCapture` | `TransitionEventHandler<HTMLDivElement>` | - | - |
| `onTransitionStart` | `TransitionEventHandler<HTMLDivElement>` | - | - |
| `onTransitionStartCapture` | `TransitionEventHandler<HTMLDivElement>` | - | - |
| `onFocus` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element receives focus. |
| `onBlur` | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the element loses focus. |
| `onFocusChange` | `((isFocused: boolean) => void)` | - | Handler that is called when the element's focus status changes. |
| `onChange` | `((value: TimeValue) => void)` | - | Handler that is called when the value changes. |

### Accessibility

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` | - | Defines a string value that labels the current element. |
| `aria-labelledby` | `string` | - | Identifies the element (or elements) that labels the current element. |
| `aria-describedby` | `string` | - | Identifies the element (or elements) that describes the object. |
| `aria-details` | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-errormessage` | `string` | - | Identifies the element that provides an error message for the object. |


## Guidelines

# Grundlagen

Die Rating Component dient zur visuellen Darstellung einer Bewertungsskala von 0
bis 5 Sternen. Sie wird häufig eingesetzt, um Bewertungen auf einen Blick
verständlich zu machen. Typische Anwendungsfälle sind Userfeedback sowie die
Bewertung von Produkten und Leistungen.

## Best practices

Achte bei der Verwendung eines Ratings darauf, dass ...

- die visuelle Darstellung immer durch ergänzenden Kontext unterstützt wird,
  z. B. durch eine Beschriftung oder eine Kombination mit anderen Components wie
  der [BigNumber](/04-components/data-visualisation/big-number/overview).
- eine konsistente Verwendung innerhalb eines Interfaces gewährleistet ist, etwa
  durch eine einheitliche Skalierung (0 bis 5 Sterne).
- unterstützende visuelle Elemente (z. B. der
  [AccentBox](/04-components/structure/accent-box/overview)) eingesetzt werden
  können, um das Rating optisch hervorzuheben.

## Verwendung

Verwende ein Rating, um ...

- Userbewertungen sichtbar zu machen, z. B. bei Rezensionen oder
  Produktempfehlungen.
- den Kontext einer Zahl oder Kennzahl (z. B. der
  [BigNumber](/04-components/data-visualisation/big-number/overview)) zu
  verdeutlichen, etwa zur Einordnung auf einer Bewertungsskala.
- Einschätzungen oder qualitative Urteile schnell erfassbar darzustellen, etwa
  bei Auswertungen.