Configuration

The main widget configuration happens when you call window.uj.init(...). Start there for the default position, theme, trigger behavior, and locale.

window.uj.init('YOUR_PROJECT_ID', {
  widget: true,
  position: 'right',
  theme: 'auto',
  trigger: 'default',
  locale: 'auto',
  onReady: () => {},
  onError: (error) => {}
});

Core options

Widget

Use widget: true to enable the floating widget.

window.uj.init('YOUR_PROJECT_ID', {
  widget: true
});

If you omit it, the SDK can still be used for other flows, but the default widget launcher will not appear.

Position

Use position to choose which side of the screen the launcher appears on.

Supported values:

window.uj.init('YOUR_PROJECT_ID', {
  widget: true,
  position: 'left'
});

Theme

Use theme to control the widget color mode.

Supported values:

window.uj.init('YOUR_PROJECT_ID', {
  widget: true,
  theme: 'dark'
});

Trigger

Use trigger to decide whether UserJot shows the default floating launcher or waits for your own UI to open it.

Supported values:

window.uj.init('YOUR_PROJECT_ID', {
  widget: true,
  trigger: 'custom'
});

If you use trigger: 'custom', the widget is still installed, but you need to open it from your own button or interaction.

Here is the usual pattern:

window.uj.init('YOUR_PROJECT_ID', {
  widget: true,
  trigger: 'custom'
});
 
document
  .querySelector('[data-feedback-button]')
  ?.addEventListener('click', () => {
    window.uj.showWidget({ section: 'feedback' });
  });

Locale

Use locale when you want to control the widget language from your product.

window.uj.init('YOUR_PROJECT_ID', {
  widget: true,
  locale: 'fr-FR'
});

If you leave locale as 'auto', UserJot chooses the language automatically. That is usually the right default unless your app already has a stronger source of truth for language.

const userLocale = getUserLocale();
 
window.uj.init('YOUR_PROJECT_ID', {
  widget: true,
  locale: userLocale
});

Lifecycle callbacks

onReady

Use onReady when you need to wait until the SDK is fully initialized before running dependent code.

window.uj.init('YOUR_PROJECT_ID', {
  widget: true,
  onReady: () => {
    console.log('UserJot is ready');
  }
});

onError

Use onError to capture initialization failures such as configuration mistakes or loading problems.

window.uj.init('YOUR_PROJECT_ID', {
  widget: true,
  onError: (error) => {
    console.error('UserJot failed to initialize:', error.message);
  }
});

Changing configuration after initialization

Some widget behavior can be updated after the initial init() call.

Change the widget position

window.uj.setWidgetPosition('left');

Change the theme

window.uj.setTheme('dark');

Temporarily disable or re-enable the widget

window.uj.setWidgetEnabled(false);
window.uj.setWidgetEnabled(true);

This is useful when the widget should only be available in certain parts of your app or for certain user states.

Programmatic control

Once the widget is initialized, you can control it from your own UI and app logic.

Open a specific section

window.uj.showWidget({ section: 'feedback' });
window.uj.showWidget({ section: 'roadmap' });
window.uj.showWidget({ section: 'updates' });

Close the widget

window.uj.hideWidget();

Send users to the public UserJot site instead

If you want a full-page public experience instead of opening the floating widget, use redirect(...):

window.uj.redirect({ to: 'feedback' });
window.uj.redirect({ to: 'feedback', openFeedback: true });
window.uj.redirect({ to: 'updates', newTab: true });

That is useful when your product has both an in-app widget and public UserJot pages.

Common configuration patterns

Minimal setup

window.uj.init('YOUR_PROJECT_ID', {
  widget: true
});

Match the app theme automatically

window.uj.init('YOUR_PROJECT_ID', {
  widget: true,
  theme: 'auto'
});

Use your own launcher

window.uj.init('YOUR_PROJECT_ID', {
  widget: true,
  trigger: 'custom'
});

Force a specific locale

window.uj.init('YOUR_PROJECT_ID', {
  widget: true,
  locale: 'en-US'
});

How to think about configuration

Use init() for the default behavior you want on first load.

Use runtime methods such as setTheme, setWidgetPosition, and setWidgetEnabled when the widget needs to react to app state after the page has already loaded.

If you want a full page embedded experience instead of the floating widget, use the iframe guide at /docs/iframe-embed.

If you want the full SDK surface area in one place, use /docs/widget-sdk-reference.