add-product-announcement

Add a product announcement with @tour-kit/announcements

Use @tour-kit/announcements when the user wants to surface a one-time or recurring message to users — modal popups, top/bottom banners, toast notifications, side slideouts, or element spotlights. Comes with five UI variants out of the box, frequency rules (once, session, every-N-days), priority queueing, and audience targeting.

Install

pnpm add @tour-kit/announcements

Minimal working example (modal)

'use client'
import { AnnouncementsProvider, AnnouncementModal } from '@tour-kit/announcements'

export function App() {
  return (
    <AnnouncementsProvider
      announcements={[
        {
          id: 'welcome-v2',
          variant: 'modal',
          title: 'Welcome to v2',
          description: 'We rebuilt the dashboard from scratch. Here\'s what changed.',
          frequency: 'once',
          priority: 'high',
        },
      ]}
    >
      <AnnouncementModal id="welcome-v2" />
      {/* rest of app */}
    </AnnouncementsProvider>
  )
}

The modal auto-shows on mount (since 0.1.5), once per user, and remembers dismissal in localStorage.

Variants — pick one

Variant	Component	Use for
modal	AnnouncementModal	Important news, blocking attention
slideout	AnnouncementSlideout	Detailed updates with multiple paragraphs
banner	AnnouncementBanner	Persistent top/bottom strip (maintenance, promos)
toast	AnnouncementToast	Lightweight corner notification, auto-dismiss
spotlight	AnnouncementSpotlight	Highlight a specific element with floating tip

Set variant in the config to match the component you render.

Frequency rules

• 'once' — show one time ever (per user)
• 'session' — show once per browser session
• 'always' — show every time eligibility passes
• { type: 'times', count: 3 } — show up to N times
• { type: 'interval', days: 7 } — show every N days

Common follow-ups

Imperative trigger

import { useAnnouncement } from '@tour-kit/announcements'

const { show, dismiss } = useAnnouncement('welcome-v2')

Audience targeting

Pass userContext to the provider, then add audience: { plan: 'pro' } to a config to gate by user attributes.

Schedule (time-based)

Install @tour-kit/scheduling and add schedule: { startAt, endAt, daysOfWeek, timeOfDay } to a config — useful for promos that should only run during business hours.

Headless

Use HeadlessModal, HeadlessBanner, etc. from @tour-kit/announcements to bring your own UI.

Gotchas

• Auto-show is on by default (0.1.5+). Set autoShow: false per-config to trigger only via show(id).
• Frequency persists to localStorage. Clearing storage / incognito resets the rule.
• Priority queueing: if multiple eligible announcements compete for the same slot, higher priority wins. Default priority is normal.
• Next.js: provider is client-only.

Reference

• Docs: https://usertourkit.com/docs/announcements
• Troubleshooting: https://usertourkit.com/docs/troubleshooting
• npm: https://www.npmjs.com/package/@tour-kit/announcements