SeggWat LogoSeggWat
Dashboard

Helpful Rating Widget

Add thumbs up/down ratings to collect binary feedback on page helpfulness

Overview

The helpful rating widget provides a simple thumbs up/down interface perfect for collecting binary feedback on documentation pages, articles, or support content. It's lightweight, customizable, and can optionally include a comment form for detailed feedback.

Quick Start

Add the helpful rating widget to your page with a single script tag:

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

The widget appears inline at the script tag location by default, showing a "Was this page helpful?" question with Yes/No buttons.

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-questionstringdefault:"Was this page helpful?"

Custom question text to display above the buttons

Example:

html
data-question="Did this answer your question?"
data-button-colorstringdefault:"#2563eb"

Hex color code for the buttons (e.g., #10b981)

The widget automatically generates hover states and maintains accessibility.

data-show-comment-linkbooleandefault:"false"

Show "Add a comment" link after a negative rating

When enabled and the user clicks "No", they'll see a link to add additional context. If the feedback widget is also loaded on the page, it opens the feedback modal. Otherwise, it expands an inline comment form.

Example:

html
data-show-comment-link="true"
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="#article-footer"
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 issues.

data-show-powered-bybooleandefault:"false"

Show or hide the "Powered by SeggWat" branding in the footer

Note: The helpful widget defaults to hidden branding (unlike the feedback button which shows it by default).

Set to true, 1, or yes to show the branding.

data-api-urlstringdefault:"auto-detect"

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

Examples

Basic Usage

html
<!-- Appears inline at script location -->
<script src="https://seggwat.com/static/widgets/v1/seggwat-helpful.js"
        data-project-key="your-project-key"></script>

Custom Question

html
<script src="https://seggwat.com/static/widgets/v1/seggwat-helpful.js"
        data-project-key="your-project-key"
        data-question="Did this solve your problem?"></script>
html
<script src="https://seggwat.com/static/widgets/v1/seggwat-helpful.js"
        data-project-key="your-project-key"
        data-show-comment-link="true"></script>

When users click "No", they'll see an "Add a comment" link. This is especially useful when combined with the feedback button widget.

Placed in Container

html
<!-- Widget container -->
<div id="page-rating"></div>

<!-- Script can be anywhere after container -->
<script src="https://seggwat.com/static/widgets/v1/seggwat-helpful.js"
        data-project-key="your-project-key"
        data-container="#page-rating"
        data-question="Was this guide helpful?"></script>

German Language

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

Full Configuration

html
<script src="https://seggwat.com/static/widgets/v1/seggwat-helpful.js"
        data-project-key="your-project-key"
        data-question="Did this article help you?"
        data-button-color="#10b981"
        data-show-comment-link="true"
        data-language="en"
        data-version="2.1.0"
        data-show-powered-by="true"></script>

JavaScript API

The widget exposes a global API for programmatic control:

Set User ID

Associate ratings with specific users:

javascript
// Set user ID when user logs in
if (window.SeggwatHelpful) {
  SeggwatHelpful.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
SeggwatHelpful.reset();

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

Access Container

Access the widget's DOM element:

javascript
const container = SeggwatHelpful.container;
// container is the root <div> element

Combining with Feedback Widget

The helpful widget works seamlessly with the feedback button. When both are loaded and data-show-comment-link="true", clicking "Add a comment" opens the feedback modal:

html
<!-- Feedback button (floating) -->
<script src="https://seggwat.com/static/widgets/v1/seggwat-feedback.js"
        data-project-key="your-project-key"></script>

<!-- Helpful widget (inline) -->
<script src="https://seggwat.com/static/widgets/v1/seggwat-helpful.js"
        data-project-key="your-project-key"
        data-show-comment-link="true"></script>

The core library loads only once, keeping total bundle size minimal.

Use Cases

Documentation Pages

Collect feedback on help articles, API references, and tutorials. Identify which pages need improvement.

Knowledge Base

Measure the effectiveness of support articles. Track which solutions actually help users.

Blog Posts

Gauge reader satisfaction and content quality. Understand which topics resonate with your audience.

Product Guides

Validate that user manuals and onboarding guides are clear and helpful.

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 clicks "Yes" or "No"
  5. Rating submits to POST /api/v1/rating/submit
  6. Widget shows thank you message
  7. Optional: User clicks "Add a comment" to provide details

API Endpoint

The widget submits ratings to:

POST /api/v1/rating/submit

Payload:

json
{
  "project_key": "uuid",
  "value": true,  // true = helpful, false = not helpful
  "path": "/current/page/path",
  "version": "1.2.3",  // optional
  "submitted_by": "user-id-123"  // optional
}

Response: 204 No Content on success

Best Practices

Styling

The widget uses the SeggWat design system and automatically adapts to light/dark mode. It's designed to blend seamlessly with most documentation sites.

CSS Classes (for custom styling):

  • .seggwat-helpful - Root container
  • .seggwat-helpful-question - Question text
  • .seggwat-helpful-buttons - Button container
  • .seggwat-helpful-btn - Individual buttons
  • .seggwat-helpful-btn-yes - Yes button
  • .seggwat-helpful-btn-no - No button
  • .seggwat-helpful-message - Feedback messages
  • .seggwat-helpful-comment-link - "Add a comment" link

Example custom styling:

css
/* Make buttons larger */
.seggwat-helpful-btn {
  padding: 12px 24px !important;
  font-size: 16px !important;
}

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

Accessibility

The helpful widget is built with accessibility in mind:

  • Semantic HTML with proper button elements
  • ARIA labels for screen readers
  • Keyboard navigation support
  • Focus indicators
  • Sufficient color contrast
  • Disabled state for submitted ratings

Troubleshooting

Next Steps

Feedback Button

Combine with the feedback button for comprehensive feedback collection

Internationalization

Configure multi-language support for your widgets

Version Tracking

Learn how to track feedback across application versions

API Reference

Explore the SeggWat API for custom integrations

Navigation