Rating

Examples
Typescript ❤️

An accessible rating component that can be heavily customized.

Install
yarn add @atlaskit/rating
npm
@atlaskit/rating
Source
Bitbucket
Bundle
unpkg.com
Changelog
Latest

2.0.3

Patch Changes

  • Updated dependencies

Note: This component is currently in developer preview.

Please experiment with and test this package, but be aware that the API may change at any time. Use at your own risk, preferably not in production.

Composing with star group and star

RatingGroup

Container for all ratings - compose this with the out-of-the-box <Star /> or compose your own rating item with <Rating />.

Props

onChange function

Callback that is called everytime the rating changes. Use this in conjunction with value for controlled behaviour.

value => undefined

groupName string

Group name for all of the child rating items. If you have multiple ratings on the same page make sure to have a unique name for each group.

Defaults to "ak--rating-group".

defaultValue string

Will set the default checked value for a child radio rating item. Use when wanting to use this in an uncontrolled way.

Do not use with value.

value string

Value that is used to check a child rating item. Use when wanting to use this in a controlled way.

Do not use with defaultValue.

testId string

A testId prop is provided for specified elements, which is a unique string that appears as a data attribute data-testid in the rendered code, serving as a hook for automated tests.

Will set these elements:

  • The root container "{testId}--root"
  • The empty input "{testId}--input-empty" which is used to signify "nothing is selected yet".

children union required

Pass in child rating items. This component expects the markup to be defined in a particular way, so if you pass extra wrapping markup expect undefined behaviour.

You can have any amount of child rating items.

One of
JSX.Element,
Array
JSX.Element

Star

This is a composed <Rating /> that is displayed as a star.

Don't use this by itself - it won't work as you expect it to. Use this in conjunction with <RatingGroup />.

Composing with star

Props

size union

Size of the star icon.

Defaults to "large".

One of
"small",
"medium",
"large",
"xlarge"

color string

Color of the star icon, when wanting to customize the color please ensure you use colors from @atlaskit/theme.

Defaults to colors.Y200.

label string required

Label for the rating item. This will be read by screen readers as well as used in the tooltip when hovering over the item.

name string

This is passed to the radio button input.

When using this with the <Rating /> component this is handled for you.

isChecked boolean

Sets checked state on the rating item.

When using this with the <Rating /> component this is handled for you.

testId string

A testId prop is provided for specified elements, which is a unique string that appears as a data attribute data-testid in the rendered code, serving as a hook for automated tests.

Will set two elements:

  • The label as "{testId}--label"
  • The radio button as "{testId}--input"
  • The unchecked icon container "{testId}--icon-container"
  • The checked icon container "{testId}--icon-checked-container"

When using this with the <Rating /> component this will inherit its testId as "{testId}--{index}--{element}", for example label would be "{testId}--{index}--label".

value string required

Value of the rating item. This will be passed back in the onChange() handler when checked.

id string

Id that is passed to both the label and the radio button element. This is needed to declare their relationship.

When using this with the <Rating /> component this is handled for you.

onChange function

Handler that is called back whenever the radio button element changes its checked state. When checked will be passed the value - when unchecked will be passed undefined.

When using this with the <Rating /> component this is handled for you.

value => undefined

Rating

Rating item component that is highly customizable. It uses a radio input as its underlying markup to ensure accessibility for screen readers and keyboard interactions.

Don't use this by itself - it won't work as you expect it to. Use this in conjunction with <RatingGroup />.

Composing with rating

Props

render function required

Render callback that should return a ReactNode. Is passed an argument which is an object with one property isChecked.

props => React.ReactNode

label string required

Label for the rating item. This will be read by screen readers as well as used in the tooltip when hovering over the item.

name string

This is passed to the radio button input.

When using this with the <Rating /> component this is handled for you.

isChecked boolean

Sets checked state on the rating item.

When using this with the <Rating /> component this is handled for you.

testId string

A testId prop is provided for specified elements, which is a unique string that appears as a data attribute data-testid in the rendered code, serving as a hook for automated tests.

Will set two elements:

  • The label as "{testId}--label"
  • The radio button as "{testId}--input"
  • The unchecked icon container "{testId}--icon-container"
  • The checked icon container "{testId}--icon-checked-container"

When using this with the <Rating /> component this will inherit its testId as "{testId}--{index}--{element}", for example label would be "{testId}--{index}--label".

value string required

Value of the rating item. This will be passed back in the onChange() handler when checked.

id string

Id that is passed to both the label and the radio button element. This is needed to declare their relationship.

When using this with the <Rating /> component this is handled for you.

onChange function

Handler that is called back whenever the radio button element changes its checked state. When checked will be passed the value - when unchecked will be passed undefined.

When using this with the <Rating /> component this is handled for you.

value => undefined

Gotchas

RatingGroup sets font-size to 0 to work around inline-block spacing issues (and thus all children get this via the cascade). When composing your own rating make sure to explicitly set font-size if needed like in the example above.