Installation

Add the ShipPulse script tag to your HTML. It loads asynchronously and never blocks page rendering.

html

<script
  src="https://shippulse.dev/widget.js"
  data-widget-id="YOUR_WIDGET_ID"
  async
></script>

Replace YOUR_WIDGET_ID with the ID from Dashboard → Project → Testimonials → Widgets.

Testimonial widget types

ShipPulse has 9 testimonial widget types, each optimized for a specific placement and goal. Select the type when creating a widget in Dashboard → Project → Testimonials → Widgets → New Widget.

Type	Description	Best for
wall	Masonry grid of all approved testimonials	Dedicated /testimonials or /love page
carousel	Auto-rotating horizontal slideshow with nav arrows	Landing page sections, pricing page
popup	Fixed-position corner popup that appears after a delay	Conversion optimization, checkout pages
badge	Compact star rating + review count (e.g. "4.9 ★ 120 reviews")	Navigation bars, hero sections, headers
ticker	Infinite horizontal scrolling marquee of testimonial snippets	Above-the-fold strips, social proof banners
avatarrow	Stacked customer avatars with "X happy customers" count	Hero sections, pricing tables
grid	Fixed-column grid layout (configurable 1–4 columns)	Embedded in pages with defined width
single	One featured testimonial, optionally rotating on a timer	Sidebars, checkout pages, email footers
slider	Touch-friendly swipeable card slider	Mobile-optimized landing pages

Type-specific options

Some widget types have additional data-* attributes:

Type	Attribute	Default	Description
popup	data-delay	5000	Delay in ms before popup appears
popup	data-position	"bottom-right"	bottom-left \| bottom-right \| top-left \| top-right
ticker	data-speed	30	Scroll speed in seconds for one full pass
carousel	data-autoplay	true	Auto-advance slides
carousel	data-interval	4000	Autoplay interval in ms
single	data-rotate	false	Rotate through testimonials on a timer
grid	data-columns	3	Number of grid columns (1–4)

Changelog widget

Display your latest changelog entries as a sidebar badge or drawer widget. Users can click to see all recent updates without leaving your page.

html

<script
  src="https://shippulse.dev/widget.js"
  data-widget-type="changelog"
  data-project-slug="your-project"
  data-position="bottom-right"
  async
></script>

Attribute	Default	Description
data-project-slug	—	Your project slug (required)
data-position	"bottom-right"	Badge position: bottom-left \| bottom-right \| top-right \| top-left
data-limit	5	Number of entries to show in the drawer
data-show-unread-dot	true	Show a red dot when there are unseen entries

Status badge widget

Embed a live "All systems operational" or "Incident detected" status badge on your site. Automatically reflects your current monitor status.

html

<script
  src="https://shippulse.dev/widget.js"
  data-widget-type="status"
  data-project-slug="your-project"
  async
></script>

Attribute	Default	Description
data-project-slug	—	Your project slug (required)
data-style	"pill"	pill \| dot \| full — controls badge appearance
data-link	true	Make badge clickable (links to your status page)

Feedback widget

A floating feedback button that opens a submission form. Users submit feature requests or bug reports directly from your site.

html

<script
  src="https://shippulse.dev/widget.js"
  data-widget-type="feedback"
  data-project-slug="your-project"
  data-position="bottom-right"
  async
></script>

Attribute	Default	Description
data-project-slug	—	Your project slug (required)
data-position	"bottom-right"	Button position: bottom-left \| bottom-right
data-label	"Feedback"	Label shown on the floating button
data-categories	"feature,bug"	Comma-separated categories: feature \| bug \| other

Configuration options

All options are configurable from the widget editor in the dashboard. Advanced users can override via data attributes:

html

<script
  src="https://shippulse.dev/widget.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-theme="dark"
  data-primary-color="#7c3aed"
  data-limit="6"
  data-show-rating="true"
  async
></script>

Attribute	Type	Default	Description
data-widget-id	string	—	Widget ID from dashboard (required)
data-theme	"light" \| "dark" \| "auto"	"auto"	Color scheme. auto follows the OS preference.
data-primary-color	string (hex)	"#7c3aed"	Accent color used for stars, borders, and CTAs.
data-limit	number	12	Max number of testimonials to display.
data-show-rating	boolean	true	Show star ratings.
data-show-avatar	boolean	true	Show author avatars.
data-columns	number	3	Grid columns (wall type only). Auto-adjusts on mobile.
data-border-radius	number (px)	12	Card border radius in pixels.
data-filter-rating	number (1–5)	—	Show only testimonials with this rating or higher.
data-filter-tag	string	—	Show only testimonials with this tag/label.

Shadow DOM isolation

All ShipPulse widgets render inside a Shadow DOM container. This means:

Zero CSS conflicts with your site styles
No global class name pollution
Safe to use on any site, including WordPress, Webflow, Squarespace

Lazy loading

Widgets use the Intersection Observer API to load content only when scrolled into view, reducing initial page load impact. No configuration required.

Custom CSS (Pro+)

Pro and Agency plans can inject custom CSS into the widget Shadow DOM via the widget editor in the dashboard. This allows full visual customization.

css

/* Example: change card background */
.testimonial-card {
  background: #f8f7ff;
  border: 1px solid #e2d9f3;
}

/* Example: change author name color */
.author-name {
  color: #5b21b6;
  font-weight: 700;
}

JavaScript API

After the script loads, a ShipPulse global object is available for programmatic control:

javascript

// Refresh widget data
window.ShipPulse.refresh("YOUR_WIDGET_ID")

// Listen for events
window.ShipPulse.on("ready", (widgetId) => {
  console.log("Widget loaded:", widgetId)
})

window.ShipPulse.on("testimonial:click", ({ id, widgetId }) => {
  console.log("Testimonial clicked:", id)
})

Next.js / React integration

Install the React package for a native component experience:

bash

npm install @shippulse/react

tsx

import { ShipPulseProvider, useTestimonials } from "@shippulse/react"

export default function App() {
  return (
    <ShipPulseProvider apiKey={process.env.NEXT_PUBLIC_SHIPPULSE_KEY!}>
      <TestimonialsSection />
    </ShipPulseProvider>
  )
}

function TestimonialsSection() {
  const { data: testimonials, loading } = useTestimonials({ status: "approved" })

  if (loading) return <p>Loading…</p>

  return (
    <ul>
      {testimonials?.map((t) => (
        <li key={t.id}>
          <blockquote>{t.content}</blockquote>
          <cite>{t.author_name}</cite>
        </li>
      ))}
    </ul>
  )
}

Installation

Add the ShipPulse script tag to your HTML. It loads asynchronously and never blocks page rendering.

html

<script
  src="https://shippulse.dev/widget.js"
  data-widget-id="YOUR_WIDGET_ID"
  async
></script>

Replace YOUR_WIDGET_ID with the ID from Dashboard → Project → Testimonials → Widgets.

Testimonial widget types

Type	Description	Best for
wall	Masonry grid of all approved testimonials	Dedicated /testimonials or /love page
carousel	Auto-rotating horizontal slideshow with nav arrows	Landing page sections, pricing page
popup	Fixed-position corner popup that appears after a delay	Conversion optimization, checkout pages
badge	Compact star rating + review count (e.g. "4.9 ★ 120 reviews")	Navigation bars, hero sections, headers
ticker	Infinite horizontal scrolling marquee of testimonial snippets	Above-the-fold strips, social proof banners
avatarrow	Stacked customer avatars with "X happy customers" count	Hero sections, pricing tables
grid	Fixed-column grid layout (configurable 1–4 columns)	Embedded in pages with defined width
single	One featured testimonial, optionally rotating on a timer	Sidebars, checkout pages, email footers
slider	Touch-friendly swipeable card slider	Mobile-optimized landing pages

Type-specific options

Some widget types have additional data-* attributes:

Type	Attribute	Default	Description
popup	data-delay	5000	Delay in ms before popup appears
popup	data-position	"bottom-right"	bottom-left \| bottom-right \| top-left \| top-right
ticker	data-speed	30	Scroll speed in seconds for one full pass
carousel	data-autoplay	true	Auto-advance slides
carousel	data-interval	4000	Autoplay interval in ms
single	data-rotate	false	Rotate through testimonials on a timer
grid	data-columns	3	Number of grid columns (1–4)

Changelog widget

Display your latest changelog entries as a sidebar badge or drawer widget. Users can click to see all recent updates without leaving your page.

html

<script
  src="https://shippulse.dev/widget.js"
  data-widget-type="changelog"
  data-project-slug="your-project"
  data-position="bottom-right"
  async
></script>

Attribute	Default	Description
data-project-slug	—	Your project slug (required)
data-position	"bottom-right"	Badge position: bottom-left \| bottom-right \| top-right \| top-left
data-limit	5	Number of entries to show in the drawer
data-show-unread-dot	true	Show a red dot when there are unseen entries

Status badge widget

Embed a live "All systems operational" or "Incident detected" status badge on your site. Automatically reflects your current monitor status.

html

<script
  src="https://shippulse.dev/widget.js"
  data-widget-type="status"
  data-project-slug="your-project"
  async
></script>

Attribute	Default	Description
data-project-slug	—	Your project slug (required)
data-style	"pill"	pill \| dot \| full — controls badge appearance
data-link	true	Make badge clickable (links to your status page)

Feedback widget

A floating feedback button that opens a submission form. Users submit feature requests or bug reports directly from your site.

html

<script
  src="https://shippulse.dev/widget.js"
  data-widget-type="feedback"
  data-project-slug="your-project"
  data-position="bottom-right"
  async
></script>

Attribute	Default	Description
data-project-slug	—	Your project slug (required)
data-position	"bottom-right"	Button position: bottom-left \| bottom-right
data-label	"Feedback"	Label shown on the floating button
data-categories	"feature,bug"	Comma-separated categories: feature \| bug \| other

Configuration options

All options are configurable from the widget editor in the dashboard. Advanced users can override via data attributes:

html

<script
  src="https://shippulse.dev/widget.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-theme="dark"
  data-primary-color="#7c3aed"
  data-limit="6"
  data-show-rating="true"
  async
></script>

Attribute	Type	Default	Description
data-widget-id	string	—	Widget ID from dashboard (required)
data-theme	"light" \| "dark" \| "auto"	"auto"	Color scheme. auto follows the OS preference.
data-primary-color	string (hex)	"#7c3aed"	Accent color used for stars, borders, and CTAs.
data-limit	number	12	Max number of testimonials to display.
data-show-rating	boolean	true	Show star ratings.
data-show-avatar	boolean	true	Show author avatars.
data-columns	number	3	Grid columns (wall type only). Auto-adjusts on mobile.
data-border-radius	number (px)	12	Card border radius in pixels.
data-filter-rating	number (1–5)	—	Show only testimonials with this rating or higher.
data-filter-tag	string	—	Show only testimonials with this tag/label.

Shadow DOM isolation

All ShipPulse widgets render inside a Shadow DOM container. This means:

Zero CSS conflicts with your site styles
No global class name pollution
Safe to use on any site, including WordPress, Webflow, Squarespace

Lazy loading

Widgets use the Intersection Observer API to load content only when scrolled into view, reducing initial page load impact. No configuration required.

Custom CSS (Pro+)

Pro and Agency plans can inject custom CSS into the widget Shadow DOM via the widget editor in the dashboard. This allows full visual customization.

css

/* Example: change card background */
.testimonial-card {
  background: #f8f7ff;
  border: 1px solid #e2d9f3;
}

/* Example: change author name color */
.author-name {
  color: #5b21b6;
  font-weight: 700;
}

JavaScript API

After the script loads, a ShipPulse global object is available for programmatic control:

javascript

// Refresh widget data
window.ShipPulse.refresh("YOUR_WIDGET_ID")

// Listen for events
window.ShipPulse.on("ready", (widgetId) => {
  console.log("Widget loaded:", widgetId)
})

window.ShipPulse.on("testimonial:click", ({ id, widgetId }) => {
  console.log("Testimonial clicked:", id)
})

Next.js / React integration

Install the React package for a native component experience:

bash

npm install @shippulse/react

tsx

import { ShipPulseProvider, useTestimonials } from "@shippulse/react"

export default function App() {
  return (
    <ShipPulseProvider apiKey={process.env.NEXT_PUBLIC_SHIPPULSE_KEY!}>
      <TestimonialsSection />
    </ShipPulseProvider>
  )
}

function TestimonialsSection() {
  const { data: testimonials, loading } = useTestimonials({ status: "approved" })

  if (loading) return <p>Loading…</p>

  return (
    <ul>
      {testimonials?.map((t) => (
        <li key={t.id}>
          <blockquote>{t.content}</blockquote>
          <cite>{t.author_name}</cite>
        </li>
      ))}
    </ul>
  )
}

Widget Reference

Installation

Testimonial widget types

Type-specific options

Changelog widget

Status badge widget

Feedback widget

Configuration options

Shadow DOM isolation

Lazy loading

Custom CSS (Pro+)

JavaScript API

Next.js / React integration

Widget Reference

Installation

Testimonial widget types

Type-specific options

Changelog widget

Status badge widget

Feedback widget

Configuration options

Shadow DOM isolation

Lazy loading

Custom CSS (Pro+)

JavaScript API

Next.js / React integration