SeggWat LogoSeggWat
Dashboard

Star Rating Widget

Collect star and smiley face ratings to measure user satisfaction

Overview

The star rating widget provides two rating styles for collecting user satisfaction data: classic star ratings (configurable from 1 to 10 stars) and emoji smiley faces (3 or 5 options). It supports half-star precision, keyboard navigation, and full internationalization.

Quick Start

Add star ratings to your page with a single script tag:

html
<script src="https://seggwat.com/static/widgets/v1/seggwat-rating.js"
        data-project-key="your-project-key"></script>

For smiley face ratings:

html
<script src="https://seggwat.com/static/widgets/v1/seggwat-rating.js"
        data-project-key="your-project-key"
        data-style="smiley"></script>

The widget appears inline at the script tag location by default, showing a label and interactive rating controls.

Configuration Options

Customize the widget's appearance and behavior using data attributes:

Required Attributes

data-project-keystringrequired

Your unique project identifier from the SeggWat dashboard

Optional Attributes

data-stylestringdefault:"stars"

Rating display style

  • stars — Classic star rating (default)
  • smiley — Emoji smiley face rating

Example:

html
data-style="smiley"
data-max-starsnumberdefault:"5"

Number of stars to display (stars mode only). Accepts values from 1 to 10.

Example:

html
data-max-stars="10"
data-facesnumberdefault:"3"

Number of smiley faces (smiley mode only). Only 3 or 5 are supported.

  • 3 — Bad, Okay, Great
  • 5 — Terrible, Bad, Okay, Good, Great

Example:

html
data-faces="5"
data-labelstringdefault:"auto"

Custom label text above the rating controls. You can also use data-question as an alias.

Defaults to "Rate your experience" for stars and "How was your experience?" for smiley mode. Translated automatically based on language.

data-allow-halfbooleandefault:"false"

Enable half-star ratings for more precise feedback (stars mode only)

Example:

html
data-allow-half="true"
data-show-countbooleandefault:"true"

Display the numeric rating counter (e.g., "3/5") next to the stars

Set to false to hide the counter.

data-inlinebooleandefault:"false"

Remove the top border styling for a more compact look

Useful when embedding the widget inside existing UI components.

data-colorstringdefault:"#f59e0b"

Hex color code for filled stars and active smiley highlights

Example:

html
data-color="#ef4444"
data-containerstring

CSS selector for custom placement

By default, the widget inserts inline at the script tag location. Use this to place it in a specific container.

Example:

html
data-container="#rating-section"
data-languagestringdefault:"auto-detect"

Language code for the widget UI

Supported languages: en, de, sv

Falls back to English if unsupported. Auto-detects from browser if not specified.

data-versionstring

Track ratings against specific application versions (e.g., 1.2.3, v2.0.0-beta)

Helps correlate ratings with releases and identify version-specific satisfaction trends.

data-show-powered-bybooleandefault:"true"

Show or hide the "Powered by SeggWat" branding

Set to false, 0, or no to hide the branding.

data-api-urlstringdefault:"auto-detect"

Override the API endpoint (useful for self-hosted or staging environments)

Examples

Basic Star Rating

html
<script src="https://seggwat.com/static/widgets/v1/seggwat-rating.js"
        data-project-key="your-project-key"></script>

10-Star Scale

html
<script src="https://seggwat.com/static/widgets/v1/seggwat-rating.js"
        data-project-key="your-project-key"
        data-max-stars="10"
        data-show-count="true"></script>

Half-Star Precision

html
<script src="https://seggwat.com/static/widgets/v1/seggwat-rating.js"
        data-project-key="your-project-key"
        data-allow-half="true"
        data-color="#ef4444"></script>

Smiley Faces (3 Options)

html
<script src="https://seggwat.com/static/widgets/v1/seggwat-rating.js"
        data-project-key="your-project-key"
        data-style="smiley"></script>

Shows three emoji faces: Bad, Okay, Great.

Smiley Faces (5 Options)

html
<script src="https://seggwat.com/static/widgets/v1/seggwat-rating.js"
        data-project-key="your-project-key"
        data-style="smiley"
        data-faces="5"></script>

Shows five emoji faces: Terrible, Bad, Okay, Good, Great.

Custom Label

html
<script src="https://seggwat.com/static/widgets/v1/seggwat-rating.js"
        data-project-key="your-project-key"
        data-label="How would you rate this product?"></script>

German Language

html
<script src="https://seggwat.com/static/widgets/v1/seggwat-rating.js"
        data-project-key="your-project-key"
        data-language="de"></script>

Full Configuration

html
<script src="https://seggwat.com/static/widgets/v1/seggwat-rating.js"
        data-project-key="your-project-key"
        data-style="stars"
        data-max-stars="5"
        data-allow-half="true"
        data-show-count="true"
        data-color="#f59e0b"
        data-label="Rate your experience"
        data-language="en"
        data-version="2.1.0"
        data-show-powered-by="false"></script>

JavaScript API

The widget exposes a global API for programmatic control:

Set User ID

Associate ratings with specific users:

javascript
if (window.SeggwatRating) {
  SeggwatRating.setUser('user_12345');
}

Validation:

  • Max 255 characters
  • Alphanumeric characters, hyphens, and underscores only
  • Examples: user_12345, cust-abc-123, USR_98765

Reset Widget

Reset the widget to its initial state:

javascript
SeggwatRating.reset();

This clears the current rating and returns to the idle state, allowing the user to rate again.

Get Current Rating

Retrieve the current rating value:

javascript
const rating = SeggwatRating.getRating();
// Returns 0 if no rating has been submitted

Get Current Style

Check which rating style is active:

javascript
const style = SeggwatRating.getStyle();
// Returns "stars" or "smiley"

Access Container

Access the widget's DOM element:

javascript
const container = SeggwatRating.container;

Keyboard Navigation

The widget supports full keyboard navigation:

Key Action
Arrow Left / Arrow Down Decrease rating by one
Arrow Right / Arrow Up Increase rating by one
Enter / Space Submit the current rating

Focus indicators are visible when navigating with the keyboard.

Use Cases

Product Pages

Let customers rate products with familiar star ratings. Compare satisfaction across your catalog.

SaaS Applications

Measure feature satisfaction with quick smiley ratings. Track happiness over time and across releases.

Support Articles

Go beyond helpful/not helpful with granular star ratings on support content.

E-commerce

Collect post-purchase ratings inline on order confirmation or product detail pages.

How It Works

  1. The script loads and auto-detects your site's base URL
  2. Core library loads automatically if not already present
  3. Widget inserts at script location (or specified container)
  4. User interacts with stars or smiley faces
  5. Rating submits to POST /api/v1/ratings
  6. Widget shows thank you message
  7. Widget enters submitted state (no duplicate submissions)

API Endpoint

The widget submits ratings to:

POST /api/v1/ratings

Payload:

json
{
  "project_key": "uuid",
  "rating": {
    "type": "star",
    "value": 4,
    "max_stars": 5
  },
  "context": {
    "path": "/current/page/path",
    "version": "1.2.3",
    "submitted_by": "user-id-123"
  }
}
  • rating.value — The selected rating (1 to max_stars, supports 0.5 increments with half-stars)
  • rating.max_stars — The configured maximum (1-10)
  • context.version — Only included if data-version is set
  • context.submitted_by — Only included if setUser() was called

Response: 201 Created on success

Best Practices

Styling

The widget uses the SeggWat design system and adapts to light/dark mode automatically.

CSS Classes (for custom styling):

  • .seggwat-star-widget — Root container
  • .seggwat-star-bordered — Applied when not inline
  • .seggwat-star-inner — Inner wrapper
  • .seggwat-star-label — Label text
  • .seggwat-star-container — Stars/smiley container
  • .seggwat-star-rating — Star rating group
  • .seggwat-star — Individual star
  • .seggwat-star.filled — Filled star
  • .seggwat-star.half-filled — Half-filled star
  • .seggwat-star-count — Rating counter
  • .seggwat-star-hover-text — Hover description text
  • .seggwat-smiley-faces — Smiley container
  • .seggwat-smiley-face — Individual smiley button
  • .seggwat-smiley-face.selected — Selected smiley
  • .seggwat-smiley-face.dimmed — Dimmed after submission
  • .seggwat-smiley-emoji — Emoji element
  • .seggwat-smiley-label — Label below emoji

Example custom styling:

css
/* Change star size */
.seggwat-star {
  font-size: 32px !important;
}

/* Custom label styling */
.seggwat-star-label {
  font-size: 18px !important;
  font-weight: 600 !important;
}

Accessibility

The star rating widget is built with accessibility in mind:

  • ARIA radiogroup role with individual radio roles for each option
  • Keyboard navigation with arrow keys and Enter/Space
  • Focus indicators for keyboard users
  • Hover text descriptions for each star level
  • Disabled state after submission
  • Sufficient color contrast

Troubleshooting

Next Steps

Feedback Button

Combine with the feedback button for comprehensive feedback collection

Helpful Rating

Use binary helpful/not helpful ratings for documentation pages

Internationalization

Configure multi-language support for your widgets

API Reference

Explore the SeggWat API for custom integrations

Navigation