Star Rating Widget

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.

Both star and smiley modes submit to the same unified rating API, making it easy to compare data across styles.

Quick Start

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

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

For smiley face ratings:

<script src="https://seggwat.com/static/widgets/v1/seggwat-star.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-key

string

required

Your unique project identifier from the SeggWat dashboard

Optional Attributes

data-style

string

default:"stars"

Rating display style

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

Example:

data-style="smiley"

data-max-stars

number

default:"5"

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

data-max-stars="10"

data-faces

number

default:"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:

data-faces="5"

data-label

string

default:"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-half

boolean

default:"false"

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

data-allow-half="true"

data-show-count

boolean

default:"true"

Display the numeric rating counter (e.g., “3/5”) next to the starsSet to false to hide the counter.

data-inline

boolean

default:"false"

Remove the top border styling for a more compact lookUseful when embedding the widget inside existing UI components.

data-color

string

default:"#f59e0b"

Hex color code for filled stars and active smiley highlightsExample:

data-color="#ef4444"

data-container

string

CSS selector for custom placementBy default, the widget inserts inline at the script tag location. Use this to place it in a specific container.Example:

data-container="#rating-section"

data-language

string

default:"auto-detect"

Language code for the widget UISupported languages: en, de, svFalls back to English if unsupported. Auto-detects from browser if not specified.

data-version

string

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-by

boolean

default:"true"

Show or hide the “Powered by SeggWat” brandingSet to false, 0, or no to hide the branding.

data-api-url

string

default:"auto-detect"

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

Examples

Basic Star Rating

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

10-Star Scale

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

Half-Star Precision

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

Smiley Faces (3 Options)

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

Shows three emoji faces: Bad, Okay, Great.

Smiley Faces (5 Options)

<script src="https://seggwat.com/static/widgets/v1/seggwat-star.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

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

German Language

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

Full Configuration

<script src="https://seggwat.com/static/widgets/v1/seggwat-star.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:

if (window.SeggwatStar) {
  SeggwatStar.setUser('user_12345');
}

Only pass user IDs, not personally identifiable information (PII) like emails or names. This maintains GDPR compliance.

Validation:

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

Reset the widget to its initial state:

SeggwatStar.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:

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

Get Current Style

Check which rating style is active:

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

Access Container

Access the widget’s DOM element:

const container = SeggwatStar.container;

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

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

API Endpoint

The widget submits ratings to:

POST /api/v1/ratings

Payload:

{
  "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

Choose the Right Style

Use stars for detailed feedback (product ratings, feature satisfaction). Use smiley faces for quick pulse checks (post-interaction, support articles).

Match the Scale to Context

A 5-star scale works for most use cases. Use 10 stars when you need finer granularity (e.g., NPS-style surveys). Use 3 smiley faces for the quickest feedback.

Match Your Audience

Set data-language to match your primary audience’s language. The auto-detection works well for multilingual sites.

Track by Version

Use data-version to correlate ratings with specific releases. Identify whether updates improve or hurt satisfaction.

Track Authenticated Users

For logged-in experiences, use setUser() to prevent duplicate ratings and enable per-user analytics.

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:

/* 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

Widget not appearing

Ratings not submitting

Common causes:

Check browser Network tab for failed API calls
Verify you’re viewing the correct project in dashboard
Rate limiting (10 second cooldown between submissions)
Check for CORS issues in console

Half-stars not working

Solutions:

Ensure data-allow-half="true" is set
Half-stars only work in stars mode, not smiley mode
Click on the left half of a star for a half rating

Translations not loading

Check:

Language code is valid: en, de, or sv
Network tab shows translation file loading
Falls back to English if translation file fails
Custom data-api-url points to correct server

Smiley mode showing wrong number of faces

Solutions:

Ensure data-style="smiley" is set
data-faces only accepts 3 or 5 (defaults to 3 for other values)
data-max-stars has no effect in smiley mode

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

General

Widgets

Features

​Overview

​Quick Start

​Configuration Options

​Required Attributes

​Optional Attributes

​Examples

​Basic Star Rating

​10-Star Scale

​Half-Star Precision

​Smiley Faces (3 Options)

​Smiley Faces (5 Options)

​Custom Label

​German Language

​Full Configuration

​JavaScript API

​Set User ID

​Reset Widget

​Get Current Rating

​Get Current Style

​Access Container

​Keyboard Navigation

​Use Cases

Product Pages

SaaS Applications

Support Articles

E-commerce

​How It Works

​API Endpoint

​Best Practices

​Styling

​Accessibility

​Troubleshooting

​Next Steps

Feedback Button

Helpful Rating

Internationalization

API Reference

Overview

Quick Start

Configuration Options

Required Attributes

Optional Attributes

Examples

Basic Star Rating

10-Star Scale

Half-Star Precision

Smiley Faces (3 Options)

Smiley Faces (5 Options)

Custom Label

German Language

Full Configuration

JavaScript API

Set User ID

Reset Widget

Get Current Rating

Get Current Style

Access Container

Keyboard Navigation

Use Cases

How It Works

API Endpoint

Best Practices

Styling

Accessibility

Troubleshooting

Next Steps