1.21.1 Procedures

Procedure: rating KEY: #:label #:name #:id #:value #:max #:required #:disabled #:readonly #:help-text #:error #:valid #:classes #:label-css #:help-classes #:error-css #:valid-css ¶

Render a star rating: a group of native radios, or a static score.

In its default (interactive) form the rating is a real radio group, so it works with scripting off and is navigated the way every other choice in a form is: one tab stop, then the arrow keys. Each star carries a spoken name – "3 of 5" – and the group is named by its ‘<legend>‘, which is what a screen reader announces rather than the stars themselves.

With readonly the rating is a single image with an accessible name ("4 out of 5"): the stars are then what a page shows about a score it does not let anyone change, such as an average review score.

label

The name of the group, rendered as a ‘<legend>‘.

name

The form field name; the value submitted is the number of stars chosen.

id

An explicit identifier for the group; defaults to name.

value

The number of stars that start filled. Defaults to 0.

max

How many stars there are. Defaults to 5.

required

Whether a rating has to be given.

disabled

Whether the group is disabled.

readonly

Show the score without letting it be changed.

help-text

Optional helper copy, linked with aria-describedby.

error

Optional validation message, announced with role="alert".

valid

#t to mark the rating as answered, or a string to say so in words.

classes

Classes for the field wrapper.

label-css

Classes for the legend.

help-classes

Classes for the helper copy.

error-css

Classes for the error message.

valid-css

Classes for the success message.

(rating #:label "How was your stay?" #:name "score" #:value 4)
(rating #:label "Average score" #:name "average" #:value 4 #:readonly #t)