# Rating

Rating is used to communicate user sentiment. It also allows customers to determine a sense of value of a good or a service.

## Best practices

### Do

- Use interactive rating when asking someone to provide feedback.
- Use rating display for ratings that were already submitted.
- Maintain 3:1 contrast between foreground and background and between selected and unselected states.

### Don't

- Use an interactive rating to represent a previously submitted value.
- Use the contrast exception unless the numeric value is explicit and visually hidden text is supplied.

## Behavior and states

- Interactive ratings have hover, focus, and pressed states.
- Rating displays show submitted ratings and are non-interactive.
- Rating icons can be empty, partially filled, or filled.

## Default

Source: CoreAI.

[Download source](/coreai-design-system/source/examples/components-rating--default.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { RatingProps } from "@coreai-ds/react-components";
import type { JSXElement } from "@coreai-ds/react-components";
import { Rating } from "@coreai-ds/react-components";
import * as React from 'react';

export const Default = (props: Partial<RatingProps>): JSXElement => {
    return <Rating {...props}/>;
};

export default Default;
```

## API

Generated CoreAI prop summaries, not replacement type declarations. Most native DOM/event and ARIA props are omitted. `?` means optional; JSDoc shows defaults, deprecations, and conditional requirements. Defaults assume the standard CoreAI provider.

### Rating API

Rating is a wrapper for one or more rating items that will be used to set a rating value.

```ts
interface RatingProps {
  as?: "div";

  children?: any;

  className?: string;

  /**
   * Controls the color of the Rating.
   * @default neutral
   */
  color?: string;

  /**
   * Default value of the Rating
   */
  defaultValue?: string | number | readonly string[];

  /**
   * The icon to display when the rating value is greater than or equal to the item's value.
   */
  iconFilled?: ElementType<any, keyof IntrinsicElements>;

  /**
   * The icon to display when the rating value is less than the item's value.
   */
  iconOutline?: ElementType<any, keyof IntrinsicElements>;

  /**
   * Prop to generate the aria-label for the rating inputs.
   * @default (rating) =\> `${rating}`
   */
  itemLabel?: ((rating: number) => string);

  /**
   * The max value of the rating. This controls the number of rating items displayed.
   * Must be a whole number greater than 1.
   * @default 5
   */
  max?: number;

  /**
   * Name for the Radio inputs. If not provided, one will be automatically generated
   */
  name?: string;

  /**
   * Callback when the rating value is changed by the user.
   */
  onChange?: EventHandler<RatingOnChangeEventData>;

  ref?: Ref<HTMLDivElement>;

  /**
   * Sets the size of the Rating items.
   * @default extra-large
   */
  size?: "small" | "medium" | "large" | "extra-large";

  /**
   * Sets the precision to allow half-filled shapes in Rating
   * @default 1
   */
  step?: 1 | 0.5;

  style?: CSSProperties;

  /**
   * The value of the rating
   */
  value?: number;
}
```

### RatingItem API

RatingItem is an item that will be used to set or display a rating value.

```ts
interface RatingItemProps {
  as?: "span";

  children?: any;

  className?: string;

  /**
   * Radio input slot used for full star precision
   */
  fullValueInput?: ({ as?: "input"; } & Omit<Omit<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref"> & { ref?: ((instance: HTMLInputElement | null) => void) | RefObject<HTMLInputElement> | null; }, "children"> & { children?: undefined; }) | undefined;

  /**
   * Radio input slot used for half star precision
   */
  halfValueInput?: ({ as?: "input"; } & Omit<Omit<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref"> & { ref?: ((instance: HTMLInputElement | null) => void) | RefObject<HTMLInputElement> | null; }, "children"> & { children?: undefined; }) | undefined;

  ref?: Ref<HTMLSpanElement>;

  /**
   * Icon displayed when the rating value is greater than or equal to the item's value.
   */
  selectedIcon?: NonNullable<WithSlotShorthandValue<{ as?: "div"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & { ref?: ((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null; }, "children"> & { children?: any; }> | null> | undefined;

  style?: CSSProperties;

  /**
   * Icon displayed when the rating value is less than the item's value.
   */
  unselectedIcon?: NonNullable<WithSlotShorthandValue<{ as?: "div"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & { ref?: ((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null; }, "children"> & { children?: any; }> | null> | undefined;

  /**
   * The positive whole number value that is displayed by this RatingItem
   */
  value?: number;
}
```

## Implementation

CoreAI 0.12.0; Fluent 9.74.9.

[Setup and dependencies](/coreai-design-system/guides/Package.md).

Import components from `@coreai-ds/react-components`. CoreAI guidance above takes precedence over API demonstration examples.

## Color

Source: Fluent, adapted for CoreAI.

A Rating's `color` can be `neutral` (default), `brand`, or `marigold`.

[Download source](/coreai-design-system/source/examples/components-rating--color.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { makeStyles } from "@coreai-ds/react-components";
import { Rating } from "@coreai-ds/react-components";
import * as React from 'react';

const useStyles = makeStyles({
    root: {
        display: 'flex',
        flexDirection: 'column',
        gap: '10px',
    },
});

export const Color = (): JSXElement => {
    const styles = useStyles();
    return (<div className={styles.root}>
      <Rating defaultValue={3}/>

      <Rating color="brand" defaultValue={3}/>

      <Rating color="marigold" defaultValue={3}/>
    </div>);
};

export default Color;
```

## Controlled Value

Source: Fluent, adapted for CoreAI.

The selected rating value can be controlled using the `value` and `onChange` props.

[Download source](/coreai-design-system/source/examples/components-rating--controlled-value.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import * as React from 'react';
import { Rating } from "@coreai-ds/react-components";
import { Button } from "@coreai-ds/react-components";

export const ControlledValue = (): JSXElement => {
    const [value, setValue] = React.useState(4);
    return (<>
      <Rating value={value} onChange={(_, data) => setValue(data.value)}/>
      <Button onClick={() => setValue(0)}>Clear Rating</Button>
    </>);
};

export default ControlledValue;
```

## Max

Source: Fluent, adapted for CoreAI.

You can specify the number of elements in the Rating with the `max` prop.

[Download source](/coreai-design-system/source/examples/components-rating--max.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { Rating } from "@coreai-ds/react-components";
import * as React from 'react';

export const Max = (): JSXElement => {
    return <Rating max={10} defaultValue={5}/>;
};

export default Max;
```

## Shape

Source: Fluent, adapted for CoreAI.

You can pass in custom icons to the Rating component. You can specify the icons with the `iconFilled` and `iconOutline` props.

[Download source](/coreai-design-system/source/examples/components-rating--shape.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { makeStyles } from "@coreai-ds/react-components";
import { Rating } from "@coreai-ds/react-components";
import { CircleFilled } from "@fluentui/react-icons";
import { CircleRegular } from "@fluentui/react-icons";
import { SquareFilled } from "@fluentui/react-icons";
import { SquareRegular } from "@fluentui/react-icons";
import * as React from 'react';

const useStyles = makeStyles({
    root: {
        display: 'flex',
        flexDirection: 'column',
        gap: '10px',
    },
});

export const Shape = (): JSXElement => {
    const styles = useStyles();
    return (<div className={styles.root}>
      <Rating iconFilled={CircleFilled} iconOutline={CircleRegular} step={0.5}/>
      <Rating iconFilled={SquareFilled} iconOutline={SquareRegular} step={0.5}/>
    </div>);
};

export default Shape;
```

## Size

Source: Fluent, adapted for CoreAI.

A Rating's `size` can be `small`, `medium`, `large`, or `extra-large`.

[Download source](/coreai-design-system/source/examples/components-rating--size.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { makeStyles } from "@coreai-ds/react-components";
import { Rating } from "@coreai-ds/react-components";
import * as React from 'react';

const useStyles = makeStyles({
    root: {
        display: 'flex',
        flexDirection: 'column',
        gap: '10px',
    },
});

export const Size = (): JSXElement => {
    const classes = useStyles();
    return (<div className={classes.root}>
      <Rating defaultValue={3} size="small"/>
      <Rating defaultValue={3} size="medium"/>
      <Rating defaultValue={3} size="large"/>
      <Rating defaultValue={3} size="extra-large"/>
    </div>);
};

export default Size;
```

## Step

Source: Fluent, adapted for CoreAI.

You can specify half values in the Rating with `step={0.5}`.

[Download source](/coreai-design-system/source/examples/components-rating--step.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { Rating } from "@coreai-ds/react-components";
import * as React from 'react';

export const Step = (): JSXElement => {
    return <Rating step={0.5} defaultValue={3.5}/>;
};

export default Step;
```

## Resources

- [Figma component](https://www.figma.com/design/eXfSQrRg3poHRgmr0ivN5V/CoreAI-Figma-Library?node-id=192287-25319)
- [Fluent guidance](https://fluent2.microsoft.design/components/web/react/core/rating/usage)