rating

Use the rating component to capture a score rating by selecting a number of icons, such as a 5 star rating.

Typical use cases include product reviews, service feedback, and surveys.

Rating component

Configuration options

Some properties are common to all components, see Common component properties for a list and their configuration options.

Core structure	Description
instanceId	The unique identifier for the rating component.
icon	The icon used for each rating step (for example, a star). If omitted, the default rating-star icon is used.
label	Provide a label/name for the rating input. Label is displayed as a placeholder when no value is provided.
maximum	The maximum rating value. This typically controls how many icons are shown, for example, 5.

Other options	Description
align	The rating component's alignment within its container can be set to left, center, or right. The default is center. An expression can also be configured to set the alignment of the rating icons.
color	Sets the color of the rating's icons. Color conditions using the when property enable dynamic color options. First evaluated to be true will be used.
errorText	Add text, string, or expressions to show text under the rating indicating an error/invalid value in the field. ErrorText is shown in isNegative styling.
helperText	Add text, strings, or expressions to guide users by displaying text beneath the rating. HelperText is displayed only when there is no errorText property set.
initialValue	The value that the rating will load with when the screen initially loads. Use this to preset a default score.
isHidden	If true the rating will be hidden on the form. If set to false the field will be shown.
isIgnored	When true, the field will be ignored during data save, and the rating value will not be stored. This property is only applied when using the submit-form action.
isRequired	Set to true when the field is required, which is indicated by a grey asterisk. Set to false, the rating is optional.
style	The following property setting is available: isDisabled - makes the rating field read-only.
value	The value to show for the rating. This is typically a numeric value representing the selected score. The value to show in the rating when the form initially loads. This can be combined with the isDisable style to preset the value that cannot be changed.

Actions	Description
onChange	The action is triggered when the value in the rating is changed. Use IntelliSense (ctrl+space) to see the list of available actions.

State Configuration	Key	Notes
=@ctx.component.state.	value	State is the variable of the component.

Considerations

• The component is available for use in a jig.default, and in a card, section, expander, and view components as children.

• If you want to display a rating inside a list item (instead of capturing input), use the rating property on a list-item.

Examples and code snippets

Basic rating

Basic rating component

Basic example to rate the safety of a building site using component.rating in a default jig. The rating value is stored in component state: =@ctx.components.rating.state.value

Examples:

See the full example in GitHub.

rating-basic.jigx

title: On-Site Safety & Risk Assessment
type: jig.default

# Simple header with an image.
header:
  type: component.jig-header
  options:
    height: small
    children:
      type: component.image
      options:
        source:
          uri: https://images.unsplash.com/photo-1701844279504-e3a974aaafb5?w=400&auto=format&fit=crop&q=60&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxzZWFyY2h8MTV8fGNvbnN0cnVjdGlvbnNpdGV8ZW58MHx8MHx8fDA%3D

children:
  # Use an entity to show contextual info above the rating.
  - type: component.entity
    options:
      children:
        - type: component.entity-field
          options:
            label: Inspection Name
            value: Park Renovation
        - type: component.entity-field
          options:
            label: Location
            value: 25 Main Street
        - type: component.field-row
          options:
            children:
              - type: component.entity-field
                options:
                  label: Inspection Date
                  value: 11-17-2025
              - type: component.entity-field
                options:
                  label: Time
                  value: 14:00

  # Rating input component.
  - type: component.rating
    instanceId: rating
    options:
      label: Overall safety condition of the site.
      # Icon controls the rating icon. The default icon is used.
      icon: rating-star
      # Maximum controls how many icons are shown.
      maximum: 5
      align: center
      # Color can be conditional using `when`.
      color:
        - when: =@ctx.component.state.value < 3
          color: negative
        - when: =@ctx.component.state.value >= 3
          color: positive

Rating on a Form

In this example the rating component is used in a hotel feedback form to score guests overall experience. The icon, color and maximum number of icons are defined.

Examples:

See the full example in GitHub.

Rating on a form

rating-form.jigx

yaml
# Hotel Feedback Form
# Purpose: Collect guest feedback after their stay at the hotel
# This form captures guest information, ratings, and overall experience
title: Hotel Feedback
type: jig.default

header:
  type: component.jig-header
  options:
    height: medium
    children:
      type: component.image
      options:
        source:
          uri: https://images.unsplash.com/photo-1566073771259-6a8506099945?w=400

children:
  - type: component.form
    instanceId: hotelFeedbackForm
    options:
      children:
        # Guest Information
        - type: component.section
          options:
            title: Guest Information
            children:
              - type: component.text-field
                instanceId: guestName
                options:
                  label: Guest Name
                  isRequired: true
              - type: component.text-field
                instanceId: roomNumber
                options:
                  label: Room Number
                  isRequired: true
              - type: component.date-picker
                instanceId: checkInDate
                options:
                  label: Check-in Date
                  isRequired: true
              - type: component.date-picker
                instanceId: checkOutDate
                options:
                  label: Check-out Date
                  isRequired: true
              - type: component.dropdown
                instanceId: visitPurpose
                options:
                  data: =@ctx.datasources.visit
                  label: Purpose of Visit
                  item:
                    type: component.dropdown-item
                    options:
                      title: =@ctx.current.item.title
                      value: =@ctx.current.item.title

        # Overall Experience. 5-star rating component for overall satisfaction.
        - type: component.section
          options:
            title: Overall Experience
            children:
              - type: component.rating
                instanceId: overallRating
                options:
                  label: Overall Stay Rating
                  # Customize the rating icon.
                  icon: rating-star-alternate
                  # Specify a color for the icons. The icon color shows
                  # when the icon is tapped.
                  color: color3
                  isRequired: true
                  # Specify the number of icons to display.
                  maximum: 5
# ============================================
# FORM SUBMISSION ACTIONS
# Sequential actions executed when form is submitted
# ============================================
actions:
  - children:
      - type: action.action-list
        options:
          title: Submit Feedback
          isSequential: true
          actions:
             # Action 1: Submit form data to local storage.
            - type: action.submit-form
              options:
                formId: hotelFeedbackForm
                provider: DATA_PROVIDER_LOCAL
                entity: hotel-feedback
                method: create
            # Action 2: Show success message to user.    
            - type: action.show-alert
              options:
                title: Thank You!
                presentAs: modal
                icon: check-circle
                subtitle: Your feedback has been submitted successfully.
                style:
                  isPositive: true

datasource

Rating with custom icon & colors

Rating with icons & color

In this example, books are reviewed by selecting a book from the list. Selecting a book opens a modal containing a rating component configured with a custom icon, color, and number of icons. An input is used to pass the book title to the modal and display it as the title of the rating component.

When a rating is submitted, the selected value is saved to the corresponding book record in the database. The BookId is passed to the modal as an input and used by the action to identify which book record to update. Once the modal closes, the saved rating value is retrieved from the database and displayed using the list-item’s rating property.

Examples:

See the full example in GitHub.

Note: This example highlights the difference between the rating component, which captures a rating, and the list-item’s rating property, which is used only to display a rating on a list item.

rating-custom-icon.jigx

# Book Reviews 
# Purpose: Display a list of books with ratings and allow users to rate each book
# Shows book cover, title, author, current rating, and provides access to rating 
# form as a modal.
title: Book reviews
type: jig.default

header:
  type: component.jig-header
  options:
    height: small
    children:
      type: component.image
      options:
        source:
          uri: https://cdn.pixabay.com/photo/2016/10/22/15/19/book-1760998_1280.jpg
# ============================================
# MAIN CONTENT: Scrollable list of books
# ============================================
children:
  - type: component.list
    options:
     # Data source binding - pulls from books datasource.
      data: =@ctx.datasources.books
      maximumItemsToRender: 8
      item:  
      # LIST ITEM- Defines how each book appears in the list.
        type: component.list-item
        options:
          title: =@ctx.current.item.title
          subtitle: =@ctx.current.item.author
          # List rating property used to display the rating value from the datasource.
          # NOTE: This is not the rating component itself. It displays the value
          # selected in the rating component in the Book Rating jig and saved to the database
          rating:
            value: =@ctx.current.item.rating
            ratingIcon:
              icon: book-star
              color: warning
              maximum: 5
          isContained: true
          # Book cover image.
          leftElement:
            element: image
            text: ""
            uri: =@ctx.current.item.image
            resizeMode: center
            size: regular
            shape: square
          # RIGHT ELEMENT: Rate button. Opens rating modal when pressed.  
          rightElement:
            element: button
            title: Rate this book
            onPress:
              type: action.go-to
              options:
                # Navigate to book-rating jig.
                linkTo: book-rating
                # Open as modal overlay (doesn't leave current screen).
                isModal: true
                inputs:
                  # Send book title to display in rating form.
                  book-title: =@ctx.current.item.title
                  # Send book ID to associate rating with correct book.
                  bookId: =@ctx.current.item.id

book-rating.jigx

datasource

Rating left aligned with helperText

In this example, the rating component is configured with custom icons that are left-aligned, along with a custom color, title, and helperText displayed beneath the icons.

Examples:

See the full example in GitHub.

Rating with helperText

rating-left-helper-text.jigx

title: Ratings
type: jig.default

header:
  type: component.jig-header
  options:
    height: small
    children:
      type: component.image
      options:
        source:
          uri: https://images.unsplash.com/photo-1585853565090-5227d79f2171?w=400&auto=format&fit=crop&q=60&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxzZWFyY2h8M3x8cmF0aW5nfGVufDB8fDB8fHww
# Resets the rating component to clear any previous selection when the screen is
# refreshed or comes into focus.
onFocus:
  type: action.reset-state
  options:
    state: =@ctx.components.rating-align.state.value
onRefresh:
  type: action.reset-state
  options:
    state: =@ctx.components.rating-align.state.value
# Rating component contained in a section component.
children:
    - type: component.section
    options:
      title:
        text: Rating left aligned with helperText
        fontSize: regular
        isBold: true
        numberOfLines: 1
        transform: uppercase
      children:
        - type: component.rating
          # Instance ID for referencing in actions and state management.
          instanceId: rating-align
          options:
            # Label displayed above the rating stars.
            label: Rate your stay
            # Thumbs-up icon instead of default stars.
            icon: thumb-up-like
            color: color3
            # Left-align the rating component (default is center).
            align: left
            # Maximum rating value (5 thumbs-up icons).
            maximum: 5
            # Helper text providing guidance to users
            helperText: Tap the stars to rate your overall experience at the resort.

Rating right aligned with initial value

Rating with initial value

In this example, the rating component is configured with custom right-aligned icons, a custom color and title, and an initialValue that is set when the screen opens. The rating can be updated by tapping the icons.

Examples:

See the full example in GitHub.

rating-right-initialvalue.jigx

title: Ratings
type: jig.default

header:
  type: component.jig-header
  options:
    height: small
    children:
      type: component.image
      options:
        source:
          uri: https://images.unsplash.com/photo-1585853565090-5227d79f2171?w=400&auto=format&fit=crop&q=60&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxzZWFyY2h8M3x8cmF0aW5nfGVufDB8fDB8fHww
# Resets the rating component's state to the initial value configured when the
# screen is refreshed or comes into focus.
onFocus:
  type: action.reset-state
  options:
    state: =@ctx.components.rating-event.state.value
onRefresh:   
  type: action.reset-state
  options:
    state: =@ctx.components.rating-event.state.value
# Rating component contained in a section component.   
children:
  - type: component.section
    options:
      title:
        text: Rating right aligned with intial value
        fontSize: regular
        isBold: true
        numberOfLines: 1
        transform: uppercase
      children:
        - type: component.rating
          # Instance ID for referencing in actions and state management.
          instanceId: rating-event
          options:
           # Label displayed above the rating icon.
            label: Rate the appointment
            icon: star-half
            color: color11
            # Preset rating value to display (two icons are selected)
            initialValue: 2
            # Right-align the rating component (default is center).
            align: right
            # Maximum rating value
            maximum: 3

Dynamic rating with conditional icons & colors

This example demonstrates an advanced rating component that dynamically changes its appearance based on user interaction. Expressions are used in the icon and color properties to conditionally apply different icons and colors based on the number of icons selected by the user.

1. When the component loads, no rating is selected

2. As the user taps icons to select a rating (1-6):

   • The @ctx.component.state.value updates immediately.

   • The icon expression evaluates and switches between happy/confused emojis.

   • The color conditions evaluate and apply the appropriate theme color

3. The user sees real-time visual feedback showing:

   • Low ratings (1-2): Red confused emoji

   • Medium rating (3): Yellow/orange confused emoji

   • High ratings (4-6): Green happy emoji

Examples:

See the full example in GitHub.

Rating icon & color set dynamically

rating-dynamic-icons.jigx

title: Ratings
type: jig.default

header:
  type: component.jig-header
  options:
    height: small
    children:
      type: component.image
      options:
        source:
          uri: https://images.unsplash.com/photo-1585853565090-5227d79f2171?w=400&auto=format&fit=crop&q=60&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxzZWFyY2h8M3x8cmF0aW5nfGVufDB8fDB8fHww
# Resets the rating component to clear any previous selection.
# Triggered when user navigates or refreshes the jig. 
onFocus:
  type: action.reset-state
  options:
    state: =@ctx.components.rating-icon.state.value
onRefresh:
  type: action.reset-state
    options:
      state: =@ctx.components.rating-icon.state.value
      
children:
  - type: component.rating
     # Instance ID for referencing this component in actions and expressions.
    instanceId: rating-icon
    options:
      # Label displayed above the rating icons.
      label: Rate this page
      # Uses ternary operator to switch between icons based on rating value.
      # Expression evaluates in real-time as user selects rating.
      # Rating 4-6 = emoji-great, Rating 1-3 = emoji-confuse-1.
      icon: =@ctx.component.state.value > 3 ? 'emoji-great' :'emoji-confuse-1'
      # Array of conditions to apply different colors based on rating.
      # Evaluated top-to-bottom; first condition that evaluates to true is used.
      color:
        - when: =@ctx.component.state.value > 3
          color: positive
        - when: =@ctx.component.state.value < 3
          color: negative
        - when: =@ctx.component.state.value = 3
          color: warning
      # Maximum rating value - creates a 6-point rating scale.    
      maximum: 6

Rating in a card

Rating in a card component

In this example, a wilderness experience is scored using the rating component, which is configured inside a card component with custom icons and a title.

Examples:

See the full example in GitHub.

rating-card.jigx

title: Ratings
type: jig.default

header:
  type: component.jig-header
  options:
    height: tiny
# Resets the rating component's state to clear the selection when the
# screen is refreshed or comes into focus.    
onFocus:
  type: action.reset-state
  options:
    state: =@ctx.components.rating-rating.state.value
onRefresh:
  type: action.reset-state
  options:
    state: =@ctx.components.rating-rating.state.value
# Rating component contained in a card component.       
children:
  - type: component.card
    options:
      # Card background color.
      color: color14
      children:
        # Image displayed in the card.
        - type: component.image
          options:
            source:
              uri: https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=400&auto=format&fit=crop&q=60&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxzZWFyY2h8Mnx8cmF0aW5nfGVufDB8fDB8fHww
        # Rating component in the card.
        - type: component.rating
          # Instance ID for referencing in actions and state management.
          instanceId: rating
          options:
            # Label displayed above the rating stars.
            label: Rate your wilderness experience
            # Default alignment of icons.
            align: center
            # Default icons.
            icon: rating-star
            # Maximum rating value
            maximum: 7