New Jersey Feedback Widget

About this component

A generic, reusable web component that can be added to any New Jersey page to get quick, in-page feedback from the user. This is inspired by the CA Design System's similar component. It is mobile-responsive, accessible (tested with axe tool), and supports English and Spanish language. See the Feedback API Github repository for the code that handles and saves this data.

User flow

1. Rating: At the bottom of a webpage, the widget asks user to rate their experience of the page with "Yes" and "No" buttons. Upon clicking an option, the rating is saved to a Google Sheet and Google Analytics (along with page URL, and submission datetime).

   Note: See only-save-rating-to-analytics attribute below for customization.

2. [OPTIONAL] Comment: Widget asks user to optionally share feedback in a free text field. Upon submitting, this text is recorded to Google Sheets.

   Note: Users often have specific questions about their situation rather than feedback.

   Note: See contact-link attribute below for customization.

3. [OPTIONAL] Email: Widget asks user to optionally share their email to join a user testing group. Upon submitting, this email is recorded to Google Sheets.

| User Submission Type | Required? | Saved to Google Analytics? | Saved to Google Sheets? | | -------------------- | --------- | -------------------------- | ----------------------- | | Rating | Yes | Yes | Yes, customizable | | Comment | No | No | Yes | | Email | No | No | Yes |

Spanish content

The component supports both English and Spanish content and offers users the ability to toggle between the two. To switch the language used within the component, use JavaScript to send a custom event using the code below:

// sending a custom changeLanguage event in a click handler for a language toggle button

document.getElementById("languageButton").addEventListener("click", (e) => {
  const customEvent = new CustomEvent("changeLanguage", {
    detail: "es" /* "en" for English or "es" for Spanish */,
    bubbles: true,
  });
  e.target.dispatchEvent(customEvent);
});

Customizable attributes

| Attribute | Description | Possible values | Defaults to | Example | Recommendations | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | contact-link | A string that can be used to set a custom URL that users are directed to if they have a specific question that they would like to have addressed. | Any URL | NJ Contact Us page URL | innovation homepage repo | N/A | | only-save-rating-to-analytics | A boolean that can be used to save ratings without comments only to Google Analytics rather than saving to the Google Sheets database | "true" or "false" | "false" | UI Claim Status web app repo | Setting to "true" is recommended for high traffic pages | | show-comment-disclaimer | A boolean that can be used to determine whether disclaimer text should be displayed in the feedback widget when users are prompted to submit a comment. This disclaimer will direct users to a separate contact form link if they have specific questions. | "true" or "false" | "true" | N/A | N/A | | skip-email-step | A boolean that can be used to determine whether to prompt the user to enter their email to join a testing group after submitting a comment. | "true" or "false" | "false" | N/A | N/A |

How to add this to your website

With Node/NPM

1. Install the latest version of the widget via the command npm i @newjersey/feedback-widget --save.
2. In the file where you would like to add a reference to the widget (likely App.tsx/App.jsx in a Create React App project), import the Javascript file to be used:

import "@newjersey/feedback-widget/feedback-widget.min.js";

3. If using TypeScript, add the following type definition to the same file you imported

declare global {
  namespace JSX {
    interface IntrinsicElements {
      "feedback-widget": React.DetailedHTMLProps<
        React.HTMLAttributes<HTMLElement>,
        HTMLElement
      >;
    }
  }
}

4. Render the feedback widget by adding the following to your HTML/JSX

<feedback-widget
  contact-link="https://www.example.com/contact"
></feedback-widget>

For website without NPM

1. Load the JS file from a CDN link by adding a script tag to your HTML.

<script
  src="https://unpkg.com/@newjersey/feedback-widget@{version}/feedback-widget.min.js"
  defer
></script>

You can change the version number after the @ sign to match your desired release (https://github.com/newjersey/feedback-widget/releases). For example, as of 10/27/2025, the latest version is 0.7.0 so you would use the following script tag:

<script
  src="https://unpkg.com/@newjersey/[email protected]/feedback-widget.min.js"
  defer
></script>

2. Render the feedback widget by adding the following tag in your HTML (likely at the bottom of the page). It's like using any other HTML tag.

<feedback-widget
  contact-link="https://www.example.com/contact"
></feedback-widget>

Troubleshooting

Don't place the feedback widget within a <form> element

The feedback widget itself contains <form> elements, and nesting <form> elements is not valid HTML.

Unexpected behavior can occur when the browser attempts to parse and render HTML that is not valid, such as stripping <form> tags out, which can break the component's functionality.

Ensure your site's CSP allows feedback widget functionality

If your site has a Content Security Policy (CSP), the following must be true for the feedback widget to function:

1. The site permits fetch requests to the Feedback API URL (https://innovation.nj.gov/app/feedback/dev).
   • Example: add "https://innovation.nj.gov" or "https://*.nj.gov" to the connect-src directive of the CSP.
2. If you're loading the widget from the UNPKG CDN (i.e. for sites without NPM), ensure UNPKG is a valid source in <script> elements.
   • Example: add "https://unpkg.com" to the script-src or script-src-elem directive of the CSP.

[FOR DEVELOPERS] How to improve this component

Minifying the JS file

Whenever there is a change to feedback-widget.js, update the minified file before committing and pushing:

1. npm install uglify-js -g (global install, not part of npm project)
2. cd feedback-widget && nvm use 18
   • NOTE: No need to cd if you're already in feedback-widget; check the .nvmrc for the latest Node version
3. uglifyjs feedback-widget.js -c -o feedback-widget.min.js

Testing your updates

Steps to test your updates on a site that embeds the feedback widget can be found in Feedback Widget Testing via DevTools.

Publishing a new version of the package

1. Go the the Draft Release action, click "Run workflow" (you need write permissions to do this). Choose the branch (main) and the semver level of the new version (patch, minor, major).
2. Confirm this worked by checking that package.json version has been bumped and a draft release for this version is available in the Releases page.
3. Click to Edit the new release, and update the description if needed. Click "Publish." This will trigger the publish-release Github Actions workflow.
4. Once the workflow is completed, confirm that the package is updated on NPM registry.

Additional documentation (internal only)

Additional documentation related to using the feedback widget and data collected. Note that this documentation is restricted only to New Jersey Office of Innovation team members.

• Getting Started with the Feedback Widget
• Analyzing Feedback Widget data with Looker Studio
• Analyzing Feedback Widget data with the AI Assistant