The rating input allows users to provide feedback based on a numeric scale represented by icons/images:
The min and max props define the minimum and maximum values an end-user can select. The max determines the number of icons rendered:
By default, the rating input will increment by 1. The step prop will allow you to set the step size between each value. For example, if you set step="0.5", the end-user can select any value that is a multiple of 0.5. Steps must be a value between 0.01 and 1:
By default, the rating input uses FormKit's own star icon. You can change which icon is being used by setting the rating-icon prop. This prop accepts a string that will use FormKit's icon plugin:
Instead of specifying an icon via the FormKit icon plugin, you can pass a raw SVG using the default slot:
Lastly, you can use the offItem and onItem slots to pass whatever assets you want.In this example, we'll use different images for the off and on states:
In addition to supplying an icon, you can also specify the color via props. Setting the off-color prop will change the color of the icons when they are not selected. The on-color prop will change the color of the icons when they are selected:
| Prop | Type | Default | Description |
|---|---|---|---|
| min | Number | 0 | The minimum number of icons that can be selected. |
| max | Number | 5 | The maximum number of icons that are rendered. |
| step | Number | 1 | The step or increment that should be applied to the `rating` icons. Accepted values are between `0.01` and `1` |
| hover-highlight | Boolean | true | Determines whether to show the selected state of the icon/image when hovered over. |
| off-color | String | undefined | Sets the color to be applied on the given icons when they have not been selected. |
| on-color | String | undefined | Sets the color to be applied on the given icons when they have been selected. |
| Show Universal props | |||
| config | Object | {} | Configuration options to provide to the input’s node and any descendent node of this input. |
| delay | Number | 20 | Number of milliseconds to debounce an input’s value before the commit hook is dispatched. |
| dirtyBehavior | string | touched | Determines how the "dirty" flag of this input is set. Can be set to touched or compare — touched (the default) is more performant, but will not detect when the form is once again matching its initial state. |
| errors | Array | [] | Array of strings to show as error messages on this field. |
| help | String | '' | Text for help text associated with the input. |
| id | String | input_{n} | The unique id of the input. Providing an id also allows the input’s node to be globally accessed. |
| ignore | Boolean | false | Prevents an input from being included in any parent (group, list, form etc). Useful when using inputs for UI instead of actual values. |
| index | Number | undefined | Allows an input to be inserted at the given index if the parent is a list. If the input’s value is undefined, it inherits the value from that index position. If it has a value it inserts it into the lists’s values at the given index. |
| label | String | '' | Text for the label element associated with the input. |
| name | String | input_{n} | The name of the input as identified in the data object. This should be unique within a group of fields. |
| parent | FormKitNode | contextual | By default the parent is a wrapping group, list or form — but this props allows explicit assignment of the parent node. |
| prefix-icon | String | '' | Specifies an icon to put in the prefixIcon section. |
| preserve | boolean | false | Preserves the value of the input on a parent group, list, or form when the input unmounts. |
| preserve-errors | boolean | false | By default errors set on inputs using setErrors are automatically cleared on input, setting this prop to true maintains the error until it is explicitly cleared. |
| sections-schema | Object | {} | An object of section keys and schema partial values, where each schema partial is applied to the respective section. |
| suffix-icon | String | '' | Specifies an icon to put in the suffixIcon section. |
| type | String | text | The type of input to render from the library. |
| validation | String, Array | [] | The validation rules to be applied to the input. |
| validation-visibility | String | blur | Determines when to show an input's failing validation rules. Valid values are blur, dirty, and live. |
| validation-label | String | {label prop} | Determines what label to use in validation error messages, by default it uses the label prop if available, otherwise it uses the name prop. |
| validation-rules | Object | {} | Additional custom validation rules to make available to the validation prop. |
| value | Any | undefined | Seeds the initial value of an input and/or its children. Not reactive. Can seed entire groups (forms) and lists.. |
You can target a specific section of an input using that section's "key", allowing you to modify that section's classes, HTML (via :sections-schema, or content (via slots)). Read more about sections here.
| Section-key | Description |
|---|---|
| itemsWrapper | A wrapper for all of the rating items (both on and off). |
| offItems | A container around all of the off items. |
| offItemWrapper | Immediate parent around each off item. |
| onItems | A container around all of the on items. |
| onItemWrapper | Immediate parent around each on item. |
| Show Universal section keys | |
| outer | The outermost wrapping element. |
| wrapper | A wrapper around the label and input. |
| label | The label of the input. |
| prefix | Has no output by default, but allows content directly before an input element. |
| prefixIcon | An element for outputting an icon before the prefix section. |
| inner | A wrapper around the actual input element. |
| suffix | Has no output by default, but allows content directly after an input element. |
| suffixIcon | An element for outputting an icon after the suffix section. |
| input | The input element itself. |
| help | The element containing help text. |
| messages | A wrapper around all the messages. |
| message | The element (or many elements) containing a message — most often validation and error messages. |
All FormKit inputs are designed with the following accessibility considerations in mind. Help us continually improve accessibility for all by filing accessibility issues here:
| Section Key | Attribute | Default | Description |
|---|---|---|---|
| label | label | for | Associates the label to an input element. Users can click on the label to focus the input or to toggle between states. |
| input | input | disabled | Disables an HTML element, preventing user interaction and signaling a non-interactive state. |
| aria-describedby | Associates an element with a description, aiding screen readers. | ||
| aria-required | Adds this attribute when validation is required. | ||
| icon | icon | for | Whenever icon is defined as a label it links it to an input element. |
| Keyboard Event | Description |
|---|---|
| Tab | Moves the focus to the next focusable input on the page. |
| Shift + Tab | Moves the focus to the previous focusable input on the page. |