Jump to section

@livstick/widget-react

Widget Documentation

Embed the Livstick video recording widget in your application. Two integration modes: React component or HTML script tag. Full CSS customization, feature flags, i18n, and event hooks.

Quick Start API Reference

Installation

Install the widget package from npm.

Install via npmbash

npm install @livstick/widget-react

Also available via:pnpm add @livstick/widget-reactyarn add @livstick/widget-react

Peer dependencies: react >= 18 and react-dom >= 18. React 19 is fully supported.

Integration Modes

Choose between React component import or HTML script tag.

HTML Script Taghtml

<div id="livstick-plugin"></div>

<script
  id="livstick-widget"
  data-uid="zqumhejbvg"
  data-lang="fr_FR"
  data-api-key="wk_xxxx"
  src="https://widget.livstick.com/assets/widget.latest.js"
></script>

Data Attributes

Attribute	Type	Description
`data-uid`	string	Unique identifier for the code/message
`data-lang`	string	Language code (e.g. fr_FR, en_US)
`data-api-key`	string	Widget API key for authentication
`data-autogenerate-urid`	boolean	Auto-generate URID if not provided
`data-sender-email`	string	Pre-fill the sender email field
`data-edit-key`	string	Edit key to authorize upload
`data-debug`	boolean	Enable debug mode (detailed errors)

Fullpage Mode

For a fullscreen integration where the widget occupies the entire viewport:

Fullpage Layouthtml

<!doctype html>
<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
    <style>
      html, body { margin: 0; padding: 0; height: 100%; width: 100%; }
      #livstick-plugin { height: 100%; width: 100%; }
    </style>
  </head>
  <body>
    <div id="livstick-plugin"></div>
    <script id="livstick-widget" data-autogenerate-urid="true"></script>
    <script type="module" src="/assets/widget.latest.js"></script>
  </body>
</html>

Customization

Customize every aspect of the widget using CSS custom properties. All variables can be overridden via the styleOverrides prop (React) or directly in your CSS.

CSS Variable	Tailwind Token	Description
`--fontFamilyTitle`	`font-title`	Title font family
`--fontFamilyText`	`font-text`	Body text font family
`--H1FontSize`	`text-title`	H1 title font size
`--H2FontSize`	`text-subtitle`	H2 title font size
`--H3FontSize`	`text-smalltitle`	H3 title font size
`--PFontSize`	`text-text`	Paragraph font size
`--inputFontSize`	`text-input`	Input text font size
`--buttonFontSize`	`text-button`	Button text font size
`--H1LetterSpacing`	`tracking-title`	H1 letter spacing
`--H2LetterSpacing`	`tracking-subtitle`	H2 letter spacing
`--H3LetterSpacing`	`tracking-smalltitle`	H3 letter spacing
`--PLetterSpacing`	`tracking-text`	Paragraph letter spacing
`--buttonLetterSpacing`	`tracking-button`	Button letter spacing
`--H1FontWeight`	`font-title`	H1 font weight
`--H2FontWeight`	`font-subtitle`	H2 font weight
`--H3FontWeight`	`font-smalltitle`	H3 font weight
`--PFontWeight`	`font-text`	Paragraph font weight
`--buttonFontWeight`	`font-button`	Button font weight
`--H2TextTransform`	`—`	CSS text-transform for H2
`--H3TextTransform`	`—`	CSS text-transform for H3
`--buttonTextTransform`	`—`	CSS text-transform for buttons

Style Overrides React only

In React mode, use the styleOverrides prop to override CSS custom properties without external stylesheets. Keys correspond to variable names without the -- prefix.

styleOverrides exampletsx

<LivstickWidget
  uid="abc123"
  apiKey="wk_xxxx"
  styleOverrides={{
    // Typography
    fontFamilyTitle: '"Playfair Display", serif',
    H1FontSize: '2rem',
    H1ColorDark: '#1a1a2e',

    // Buttons
    buttonPrimaryBackgroundColor: '#e94560',
    buttonPrimaryBackgroundColorHover: '#c73e54',
    buttonPrimaryColor: '#ffffff',
    buttonRadius: '24px',

    // Inputs
    inputBorderColor: '#ddd',
    inputRadius: '8px',

    // Layout
    widgetPadding: '16px',
  }}
/>

Priority Order

Browser defaults→API injection (`:root`)→styleOverrides

Translations (i18n)

63 translation keys organized by screen. Keys marked HTML support HTML content via dangerouslySetInnerHTML.

Intro3 keys

Key	HTML	Description
`widget_txt_intro_title`	Yes	Introduction screen title
`widget_txt_intro_description`	Yes	Introduction screen description
`widget_txt_cancel`	—	Cancel button text

Global2 keys

Key	HTML	Description
`global_txt_step`	—	"Step" label
`global_txt_title`	—	Global title

Recorder18 keys

Key	HTML	Description
`player_txt_button_start`	—	Start recording button
`player_txt_button_stop`	—	Stop recording button
`player_txt_button_retry`	—	Retry button
`player_txt_button_send`	—	Send button
`player_txt_button_import`	—	Import button
`player_txt_mobile_video_button`	—	Mobile video button
`player_txt_mobile_title`	—	Mobile title
`player_info`	Yes	Recording info
`player_info2`	Yes	Secondary recording info
`player_txt_warning_toobig_title`	—	File too large warning title
`player_txt_warning_toobig`	—	File too large warning message
`player_txt_title`	—	Recorder title
`camera_permission_title`	—	Camera permission title
`camera_permission_explanation`	—	Camera permission explanation
`camera_permission_button_allow`	—	Allow camera button
`camera_permission_button_import`	—	Import button (permission)
`camera_permission_or`	—	"or" text between options
`mobile_txt_import_library`	—	Import from library text

Form28 keys

Key	HTML	Description
`form_txt_title_form`	—	Form title
`form_txt_from`	—	"From" label
`form_txt_from_reinsurance`	—	Sender reassurance text
`form_txt_from_fname`	—	First name label
`form_txt_from_lname`	—	Last name label
`form_txt_from_email`	—	Sender email label
`form_txt_from_dob`	—	Date of birth label
`form_txt_day`	—	Day label
`form_txt_month`	—	Month label
`form_txt_year`	—	Year label
`form_txt_to`	—	"To" label
`form_txt_to_reinsurance`	—	Recipient reassurance text
`form_txt_to_email`	—	Recipient email label
`form_txt_to_bymail`	—	"By email" option label
`form_txt_to_byphone`	—	"By phone" option label
`form_txt_country`	—	Country label
`form_txt_add_message_title`	—	Message area title
`form_txt_msg_reinsurance`	—	Message reassurance text
`form_txt_add_message_placeholder`	—	Message placeholder
`form_txt_send`	—	Send button text
`form_txt_mandatory`	—	"Required fields" text
`form_txt_checkbox1`	Yes	Checkbox text (T&C / consent)
`form_txt_schedule_title`	—	Scheduling title
`form_txt_schedule_title_info`	—	Scheduling info
`form_txt_schedule_option_now`	—	"Now" option
`form_txt_schedule_option_later`	—	"Later" option
`form_txt_schedule_date`	—	Schedule date label
`form_txt_preview_unavailable`	—	Preview unavailable text

Success4 keys

Key	HTML	Description
`success_txt_success_title`	—	Success screen title
`success_txt_success`	Yes	Success message
`success_discover_your_message`	Yes	"Discover your message" text
`success_discover_your_message_button`	—	Discover button text

Loading1 keys

Key	HTML	Description
`loading_txt_sending`	—	Sending progress text

JavaScript Events

Listen for widget lifecycle events and programmatically control navigation.

livstickRecordedCustom Event

Fired when the user completes a video recording and upload. Listen on document.

document.addEventListener('livstickRecorded', () => {
  console.log('Video recorded successfully!');
  showSuccessMessage();
});

livstickRouteChangerCustom Event

Fired on internal route changes. The detail property contains the new route name.

document.addEventListener('livstickRouteChanger', (e) => {
  console.log('Widget navigated to:', e.detail);
});

window.livcr(route)Global Function

Programmatically navigate the widget to a specific route.

// Navigate to the recording screen
window.livcr('record');

// Available routes: 'intro' | 'record' | 'loading' | 'finish'

Ready to transform your customer experiences?

Let's discuss your project and discover how LIVSTICK can help you create unforgettable moments.

Response within 24h

Personalized demonstration

No commitment