Skip to main content

​
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.
See it in action at the bottom of this page!

​
Quick Start

Add the helpful rating widget to your page with a single script tag: 
<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-key
string
required
Your unique project identifier from the SeggWat dashboard

​
Optional Attributes

​
data-question
string
default:"Was this page helpful?"
Custom question text to display above the buttonsExample:
data-question="Did this answer your question?"
​
data-button-color
string
default:"#2563eb"
Hex color code for the buttons (e.g., #10b981)The widget automatically generates hover states and maintains accessibility.
​
data-show-comment-link
boolean
default:"false"
Show “Add a comment” link after a negative ratingWhen 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:
data-show-comment-link="true"
​
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="#article-footer"
​
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 issues.
​
data-show-powered-by
boolean
default:"false"
Show or hide the “Powered by SeggWat” branding in the footerNote: 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-url
string
default:"auto-detect"
Override the API endpoint (useful for self-hosted or staging environments)

​
Examples

​
Basic Usage

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

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

<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

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

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

​
Full Configuration

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

Reset the widget to its initial state: 
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: 
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: 
<!-- 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: 
{
  "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

Place the widget at the end of your content, after users have consumed the information. Common locations:
  • Bottom of documentation pages
  • End of support articles
  • After tutorial steps
Set data-show-comment-link="true" to understand why users found content unhelpful. This qualitative feedback is invaluable for improvements.
Set data-language to match your primary audience’s language. The auto-detection works well for multilingual sites.
If you version your docs or content, use data-version to correlate ratings with specific releases or updates.
For logged-in experiences, use setUser() to enable:
  • Preventing duplicate ratings from the same user
  • Following up with users who left negative ratings
  • Correlating ratings with user segments

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

Check these issues:
  • Verify the script URL is correct: https://seggwat.com/static/widgets/v1/seggwat-helpful.js
  • Ensure your project key is correct
  • Check browser console for JavaScript errors
  • If using data-container, verify the selector exists in the DOM
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
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

​
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