Rating
View .mdRating is used to communicate user sentiment. It also allows customers to determine a sense of value of a good or a service.
Default
Loading interactive example. Full source is available below.
View example source
// 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;
Resources
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.
API referenceGenerated CoreAI prop and type summaries
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.
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.
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.
Import components from @coreai-ds/react-components. CoreAI guidance above takes precedence over API demonstration examples.
Color
Loading interactive example. Full source is available below.
// 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
Loading interactive example. Full source is available below.
// 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
Loading interactive example. Full source is available below.
// 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
Loading interactive example. Full source is available below.
// 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
Loading interactive example. Full source is available below.
// 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
Loading interactive example. Full source is available below.
// 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;