Description #

Star rating selector that stores a numeric value (for example 4) and renders an interactive star UI.
Optionally displays the numeric label (4 / 5) and can be set to read-only.

This field is compatible with admin screens, frontend forms (acf_form()), and includes REST schema, REST formatting, and REST validation.

Use Cases #

• Collect quick feedback in forms (ratings)
• Add ratings to reviews, testimonials, products, or listings
• Capture internal quality checks (0–5, 0–10, etc.)
• Display a rating value consistently in admin and frontend
• Lock a rating after submission using read-only mode
• Validate rating updates via REST API for headless setups

Field Preview #

Interactive star buttons with optional numeric indicator.

• Stars: ★ ★ ★ ★ ☆
• Number (optional): 4 / 5

How to Use #

1. Add the Rating / Stars field to a Field Group
2. Set Max stars (example 5)
3. Enable or disable Show number
4. Enable Read only if the rating should not be editable
5. Save the Field Group and edit a post (or render using acf_form)

No custom code is required.

Field Settings #

Setting	Description	Default
Max stars	Maximum number of stars displayed and maximum allowed value	5
Show number	Show numeric indicator next to stars (example 4 / 5)	Enabled
Read only	Prevent editing this field in the UI	Disabled

Value & Storage #

• Saved as: Post meta
• Storage type: Hidden input storing an integer
• Return format: int (or 0 when empty)
• Allowed range: 0 to max_stars
• Render clamping: The displayed value is clamped to the configured max
• Save clamping: The stored value is clamped to the configured max
• REST: Schema min/max are derived from max_stars, with additional validation

Important details:

• 0 is valid and represents “no rating”
• In REST context, empty values can be null (schema includes null)

Output Examples #

PHP (Get numeric value) #

$rating = (int) get_field('my_rating');
echo esc_html($rating);

PHP (Render stars in theme) #

$rating = (int) get_field('my_rating');
$max    = 5;

for ($i = 1; $i <= $max; $i++) {
    echo $i <= $rating ? '★' : '☆';
}

Twig #

{{ fn('get_field', 'my_rating')|default(0) }}

Compatibility #

• Repeaters
• Flexible Content
• Options Pages
• Frontend forms (acf_form)
• REST API (schema, formatting, validation)
• Multisite

Hooks (Developer) #

Hooks Summary #

Hook	Type	Purpose
cfb/field/rating_stars/defaults	Filter	Modify default settings
cfb/field/rating_stars/supports	Filter	Modify ACF support flags
cfb/field/rating_stars/before_enqueue	Action	Run logic before assets enqueue
cfb/field/rating_stars/after_enqueue	Action	Run logic after assets enqueue
cfb/field/rating_stars/render_field_settings	Action	Add custom settings in Field Group editor
cfb/field/rating_stars/before_render	Action	Run logic before UI render
cfb/field/rating_stars/after_render	Action	Run logic after UI render
cfb/field/rating_stars/max_stars	Filter	Control max stars at runtime (render)
cfb/field/rating_stars/show_number	Filter	Toggle numeric display (render)
cfb/field/rating_stars/readonly	Filter	Toggle read-only mode (render)
cfb/field/rating_stars/value_raw	Filter	Modify raw value before clamping (render)
cfb/field/rating_stars/max_stars_save	Filter	Control max stars during save
cfb/field/rating_stars/sanitize_value	Filter	Transform value before clamping (save)
cfb/field/rating_stars/format_value	Filter	Modify value returned to templates/REST
cfb/field/rating_stars/max_stars_rest	Filter	Control max stars used in REST schema
cfb/field/rating_stars/max_stars_rest_format	Filter	Control max stars used in REST formatting
cfb/field/rating_stars/format_value_for_rest	Filter	Modify final REST output value
cfb/field/rating_stars/max_stars_rest_validate	Filter	Control max stars used in REST validation

Filters #

Defaults #

Filter: cfb/field/rating_stars/defaults
Purpose: Override default field configuration globally
When: You want consistent defaults across all Rating/Stars fields

add_filter('cfb/field/rating_stars/defaults', function ($defaults) {
    $defaults['max_stars'] = 10;
    $defaults['show_number'] = 0;
    $defaults['readonly'] = 0;
    return $defaults;
});

Supports #

Filter: cfb/field/rating_stars/supports
Purpose: Control ACF supports such as required
When: The field should not be mandatory or needs different support flags

add_filter('cfb/field/rating_stars/supports', function ($supports) {
    $supports['required'] = false;
    return $supports;
});

Max Stars (Render) #

Filter: cfb/field/rating_stars/max_stars
Purpose: Override the maximum stars at runtime used for UI and display clamping
When: Max stars depend on context (post type, role, settings, etc.)

add_filter('cfb/field/rating_stars/max_stars', function ($max_stars, $field) {
    // Example: increase scale on frontend only
    return is_admin() ? 5 : 10;
}, 10, 2);

Show Number (Render) #

Filter: cfb/field/rating_stars/show_number
Purpose: Enable/disable the numeric indicator (current / max) in the UI
When: You only want admins to see the number

add_filter('cfb/field/rating_stars/show_number', function ($show, $field) {
    return current_user_can('manage_options');
}, 10, 2);

Read Only (Render) #

Filter: cfb/field/rating_stars/readonly
Purpose: Force read-only behavior at runtime
When: Lock ratings after publish or for non-admin users

add_filter('cfb/field/rating_stars/readonly', function ($readonly, $field) {
    return !current_user_can('edit_posts');
}, 10, 2);

Raw Value (Render) #

Filter: cfb/field/rating_stars/value_raw
Purpose: Transform the incoming value before UI clamping occurs
When: You need to map legacy scales or normalize stored data for display

add_filter('cfb/field/rating_stars/value_raw', function ($value, $field) {
    // Example: map legacy 1–10 to 0–5
    return (int) round(((int) $value) / 2);
}, 10, 2);

Max Stars (Save) #

Filter: cfb/field/rating_stars/max_stars_save
Purpose: Control max stars used for validation/clamping during save
When: Save rules differ from display rules

add_filter('cfb/field/rating_stars/max_stars_save', function ($max_stars, $post_id, $field) {
    return 5;
}, 10, 3);

Sanitize Value (Save) #

Filter: cfb/field/rating_stars/sanitize_value
Purpose: Transform the submitted value before clamping and saving
When: You need business rules (rounding, allowed increments, etc.)

add_filter('cfb/field/rating_stars/sanitize_value', function ($value, $post_id, $field) {
    // Example: allow only whole numbers (already int), ensure non-negative
    return max(0, (int) $value);
}, 10, 3);

Format Value (Return) #

Filter: cfb/field/rating_stars/format_value
Purpose: Modify the value returned by get_field() and REST output
When: You need consistent normalization for consumers

add_filter('cfb/field/rating_stars/format_value', function ($value, $post_id, $field) {
    return max(0, (int) $value);
}, 10, 3);

Max Stars (REST Schema) #

Filter: cfb/field/rating_stars/max_stars_rest
Purpose: Control the max stars value used in REST schema (maximum)
When: Your REST schema differs from UI max stars

add_filter('cfb/field/rating_stars/max_stars_rest', function ($max_stars, $field) {
    return 10;
}, 10, 2);

Max Stars (REST Formatting) #

Filter: cfb/field/rating_stars/max_stars_rest_format
Purpose: Control max stars used when formatting REST output
When: You need different bounds for REST consumers

add_filter('cfb/field/rating_stars/max_stars_rest_format', function ($max_stars, $post_id, $field) {
    return 10;
}, 10, 3);

Format Value for REST #

Filter: cfb/field/rating_stars/format_value_for_rest
Purpose: Modify the final value sent in REST responses
When: You want to return null in some cases or adjust scaling

add_filter('cfb/field/rating_stars/format_value_for_rest', function ($value, $post_id, $field) {
    // Example: convert 0 to null in REST responses
    return $value === 0 ? null : (int) $value;
}, 10, 3);

Max Stars (REST Validation) #

Filter: cfb/field/rating_stars/max_stars_rest_validate
Purpose: Control the max stars used to validate REST updates
When: REST validation rules differ from UI/save rules

add_filter('cfb/field/rating_stars/max_stars_rest_validate', function ($max_stars, $field) {
    return 10;
}, 10, 2);

Actions #

Before Enqueue #

Action: cfb/field/rating_stars/before_enqueue
Runs before scripts/styles are enqueued
Useful to register dependencies, add conditions, or debug enqueues.

add_action('cfb/field/rating_stars/before_enqueue', function ($field_instance) {
    // Pre-enqueue logic
});

After Enqueue #

Action: cfb/field/rating_stars/after_enqueue
Runs after scripts/styles are enqueued
Useful for adding inline CSS/JS.

add_action('cfb/field/rating_stars/after_enqueue', function ($field_instance) {
    // Post-enqueue logic
});

Render Field Settings #

Action: cfb/field/rating_stars/render_field_settings
Runs in the Field Group editor after default settings are rendered
Useful for adding custom settings via acf_render_field_setting().

add_action('cfb/field/rating_stars/render_field_settings', function ($field) {
    // Add custom settings here
});

Before Render #

Action: cfb/field/rating_stars/before_render
Runs immediately before rendering the field UI.

add_action('cfb/field/rating_stars/before_render', function ($field) {
    // Pre-render logic
});

After Render #

Action: cfb/field/rating_stars/after_render
Runs after rendering the UI and provides the final clamped value and max stars used.

add_action(
    'cfb/field/rating_stars/after_render',
    function ($field, $value, $max_stars) {
        // Post-render logic
    },
    10,
    3
);

Assets #

This field enqueues assets whenever the input is rendered (admin and frontend via acf_form()):

• admin/css/cfb-field-rating-stars.css
• admin/js/cfb-field-rating-stars.js (dependency: acf-input)

REST API #

• Schema: integer | null
• Minimum: 0
• Maximum: Derived from max_stars (filterable)
• Default: 0

Example REST output:

{
  "my_rating": 4
}

Security & Escaping #

• UI output is escaped
• Saved values are sanitized and clamped server-side
• REST updates are validated and return clear WP_Error messages when invalid

Notes / Limitations #

• Stores only the numeric rating (not star characters)
• 0 represents “no rating”
• Changing max_stars may clamp previously saved values in UI and REST
• REST accepts null (and returns null) when value is empty

Changelog #

• 1.0.0 — Initial release