ratingField returns a Number field that stores a star rating as a whole number from 1 to max. The admin panel shows the rating as stars and edits it by clicking a star, and agents and generated types are told the allowed range. You don’t name any components or write a formatter.
number field, so it works anywhere a field does, including inside groups, arrays, tabs and blocks.
Config options
The lowest rating is always
1, so min is not accepted. A rating field holds one value, so hasMany, minRows and maxRows are not accepted either. TypeScript rejects all four, and setting any of them from JavaScript fails at startup.
Invalid options fail when the config is built, with an error naming the field:
0 and values above max fail the built-in range check, and a fraction such as 3.5 fails with:
Admin options
Rating fields support the standard field admin options. These Number field options are accepted but not used, because the rating control is a row of stars:
FrogBot stores the field’s
max in admin.custom.frogbot.kind. Your own admin.custom keys, and other keys under admin.custom.frogbot, are kept.
Display and editing
A rating showsmax stars: the first value stars are filled, and the rest are faint outlines. A rating of 3 with the default max shows three filled stars and two faint ones, and screen readers hear “3 of 5”.
An empty value shows nothing, not five faint stars. A stored value that isn’t a whole number from 1 to max, for example one saved before the field became a rating, shows as the plain stored number and never as stars.
Ratings look the same in the List, on Board cards and in Calendar events. If a rating field is the first List column, a row with an empty value has no link to open the document from that column.
In the document view, an editable rating field is a row of stars:
- Click a star to set the rating.
- Click the current star again to clear the rating.
- Use the arrow keys to move the rating up or down once a star has focus.
required and a custom validate work as on a Number field. When the field is read-only, because of admin.readOnly, because it is virtual, or because the user may not update it, the document view shows the stars with no way to change them.
Stored value
Ratings are stored as whole numbers from1 to max. The REST API, GraphQL and the Local API read and write the number, and the generated TypeScript type is the same as a Number field’s, such as score?: number | null. Filters and sorting use the stored number.
Agents and generated types
A rating field describes itself to agents using FrogBot’s MCP tools and in generated types. The text uses the field’smax:
admin.description, or a translated one with an en entry, the rating text is added after it in parentheses. The admin panel still shows only your description.
admin.description isn’t copied, so the rating text stands alone. The text is English only.
Generated types show the text as a comment above the property. In the MCP plugin’s create and update tools, the value is an integer with a minimum of 1 and a maximum of max, so agents see the allowed range. Generated types don’t include limits, and virtual fields don’t appear in MCP tool inputs.
To change the text, add your own jsonSchema entry. It runs after the rating field’s entry, so it can adjust or replace the description:
Custom components
The rating cell and input areRatingCell and RatingField from @frogbotai/ui/admin. Your own admin.components.Cell or admin.components.Field replaces them, and other components such as Label, Description, Error, beforeInput and afterInput work with the stars as they do on a Number field. frogbot/fields exports the RatingKind type for reading the field’s max in your own components.
A custom Cell can draw the standard stars inside its own markup with FieldCell, as shown for Money fields. As with any custom Cell, it appears only in the List view. Board cards and Calendar events keep the standard stars.