Events & API

Control the widget programmatically and respond to user interactions.

Getting the Widget Reference

const widget = document.querySelector('pollarix-widget');

// Or via the global API
const widget = window.Pollarix.getWidget();

---

Control Methods

show()

Display the widget:

widget.show();

hide()

Hide the widget:

widget.hide();

toggle()

Toggle visibility:

widget.toggle();

reset()

Reset the widget state (clears selected score):

widget.reset();

destroy()

Remove the widget from the DOM and clean up:

widget.destroy();

---

Configuration Methods

configure(config)

Update widget configuration:

widget.configure({
  theme: 'dark',
  text: {
    question: 'How was your experience?'
  }
});

getConfig()

Get the current configuration:

const config = widget.getConfig();
console.log(config.scale.type);  // 'nps'

setScore(score)

Programmatically select a score:

widget.setScore(9);

---

Frequency Methods

isThrottled()

Check if the widget is currently throttled:

if (widget.isThrottled()) {
  console.log('Widget is throttled');
}

clearThrottle()

Clear throttle data to allow the widget to show again:

widget.clearThrottle();

---

Read-Only Properties

Property	Type	Description
score	number | null	Currently selected score
isVisible	boolean	Widget visibility state
isSubmitting	boolean	Submission in progress

console.log(widget.score);        // 9 or null
console.log(widget.isVisible);    // true or false
console.log(widget.isSubmitting); // true or false

---

Events

All events are dispatched as CustomEvent with the pollarix: prefix.

Event List

Event	When	Detail
pollarix:ready	Widget initialized	—
pollarix:show	Widget became visible	—
pollarix:hide	Widget became hidden	—
pollarix:select	User selected a score	{ score: number }
pollarix:submit	Response submitted	{ score: number, responseId: string }
pollarix:dismiss	User dismissed widget	{ reason: string }
pollarix:close	Widget closed	{ reason: string }
pollarix:error	Error occurred	{ error: Error }

Listening to Events

const widget = document.querySelector('pollarix-widget');

widget.addEventListener('pollarix:ready', () => {
  console.log('Widget is ready');
});

widget.addEventListener('pollarix:select', (event) => {
  console.log('Score selected:', event.detail.score);
});

widget.addEventListener('pollarix:submit', (event) => {
  console.log('Submitted! Response ID:', event.detail.responseId);
});

widget.addEventListener('pollarix:dismiss', (event) => {
  console.log('Dismissed. Reason:', event.detail.reason);
  // reason: 'close-button' | 'escape' | 'outside-click'
});

widget.addEventListener('pollarix:error', (event) => {
  console.error('Error:', event.detail.error);
});

---

Analytics Integration

Using Analytics Callbacks

widget.configure({
  analytics: {
    onImpression: () => {
      // Track widget impression
      gtag('event', 'nps_widget_shown');
    },
    onInteraction: (type) => {
      // Track interactions
      gtag('event', 'nps_widget_interaction', { type });
    },
  }
});

Using Events with Analytics

Google Analytics

widget.addEventListener('pollarix:show', () => {
  gtag('event', 'nps_survey_shown');
});

widget.addEventListener('pollarix:submit', (e) => {
  gtag('event', 'nps_survey_submitted', {
    score: e.detail.score
  });
});

Segment

widget.addEventListener('pollarix:show', () => {
  analytics.track('NPS Survey Shown');
});

widget.addEventListener('pollarix:submit', (e) => {
  analytics.track('NPS Survey Submitted', {
    score: e.detail.score,
    responseId: e.detail.responseId
  });
});

Mixpanel

widget.addEventListener('pollarix:show', () => {
  mixpanel.track('NPS Survey Shown');
});

widget.addEventListener('pollarix:submit', (e) => {
  mixpanel.track('NPS Survey Submitted', {
    score: e.detail.score
  });
});

---

Global API

The widget exposes a global Pollarix object for debugging:

// Get widget reference
const widget = window.Pollarix.getWidget();

// Clear all throttle data
window.Pollarix.clearThrottle();

---

Complete Example

const widget = document.querySelector('pollarix-widget');

// Wait for widget to be ready
widget.addEventListener('pollarix:ready', () => {
  console.log('Widget initialized');

  // Configure with user data
  widget.configure({
    prefill: {
      userId: currentUser.id,
      email: currentUser.email,
    }
  });
});

// Track all interactions
widget.addEventListener('pollarix:show', () => {
  analytics.track('NPS Widget Shown');
});

widget.addEventListener('pollarix:select', (e) => {
  analytics.track('NPS Score Selected', { score: e.detail.score });
});

widget.addEventListener('pollarix:submit', (e) => {
  analytics.track('NPS Survey Completed', {
    score: e.detail.score,
    responseId: e.detail.responseId,
  });

  // Show thank you message in your UI
  showNotification('Thanks for your feedback!');
});

widget.addEventListener('pollarix:dismiss', (e) => {
  analytics.track('NPS Survey Dismissed', { reason: e.detail.reason });
});

widget.addEventListener('pollarix:error', (e) => {
  console.error('Widget error:', e.detail.error);
  errorTracking.captureException(e.detail.error);
});

---

API Reference

Methods

Method	Parameters	Returns	Description
show()	—	void	Show the widget
hide()	—	void	Hide the widget
toggle()	—	void	Toggle visibility
reset()	—	void	Reset state
destroy()	—	void	Remove widget
configure(config)	Partial<WidgetConfig>	void	Update config
getConfig()	—	WidgetConfig	Get current config
setScore(score)	number	void	Select a score
isThrottled()	—	boolean	Check throttle status
clearThrottle()	—	void	Clear throttle data

Properties

Property	Type	Description
score	number | null	Selected score
isVisible	boolean	Visibility state
isSubmitting	boolean	Submission state

---

Next Steps

• Examples - Common implementation patterns
• Configuration - All configuration options