Lighthouse Widget API

You can customize the behaviour and appearance of Lighthouse through the widget API. Learn how to do things like change the primary color, navigate to a new article, or hide the widget completely.

Taylor Sloane
Updated by Taylor Sloane

Lighthouse ships with everything you need by default. But if you're looking to customize it I come bearing good news! You can use the Lighthouse Widget API to change how it looks and behaves.

Lighthouse is available on some of our plans

Changing the Lighthouse Config

When you initialize Lighthouse you'll have used a snippet of Javascript code from your HelpDocs dashboard in Settings > Lighthouse. Something like this:

<script type="text/javascript">
window.hdlh = {
widget_key: "your-super-secret-widget-key"
(function(h,d){var s=d.createElement("script");s.type='text/javascript';s.async=true;s.src=h+"?t="+new Date().getTime();d.head.appendChild(s);})("",document);

Notice the window.hdlh object? That holds a lotta power since you can include values to change how Lighthouse looks and acts. Let's dive in and explore the different options.

window.hdlh = {
..., // the rest of your widget config would replace the ... here, e.g. your widget_key
language_code: 'fr', // Type: String. One of the language codes from your HelpDocs account.
text_direction: 'ltr|rtl', Type: String. Set to 'rtl' to change text direction to right to left. Default is left to right.
logo: '', // Type: String or Bool. An absolute URL to an image to use as the logo or pass false to disable the logo completely. Ideally an SVG but a 180px square PNG/JPG will work great.
primary_color: '#ff63aa', // Type: String. Include a hex code you'd like Lighthouse to base all other colors from.
color_mode: 'light|dark|auto', // Type: String. Force the complementary color scheme (like the headers) to become light or dark. Default is auto so we'll try to guess if your primary color needs light or dark complementary colors.
brand: 'Support', // Type: String. Change the string that shows up in the top bar of Lighthouse.
launcher_button_image: '', // Type: string. An absolute URL to an image to use as the background of the launcher button. If you don't pass this we'll use the default Lighthouse icon.
frame_width: '400px', // Type: String. How wide you'd like the main frame to appear.
position: 'bottom right|bottom left', // Type: String. Set to 'bottom left' to move Lighthouse to the left corner. Defaults to the right.
article_link_target: '_blank|_top|auto', // Type: String. ADVANCED: Set the target of all links in articles. Default is '_blank' to open in new tab. Can also be '_top' to open in same tab or 'auto' to respect what you choose in the article editor.
article_html_clean_mode: 'aggressive|standard', // Type: String. ADVANCED: By default Lighthouse aggressively cleans HTML to remove inline styles and many types of element. You can preserve inline styles, divs, spans and more by reducing the aggression. Recommended not to adjust this.
ignore_contact_widgets: true, // ADVANCED: Bool: string. Don't automatically detect contact widgets on the page and use the email form (or nothing) instead.
suggestions: [String], // Type: Array of Strings. An array of suggestions to show the user. e.g. ['tag:test','article:12a45b78', 'category:ab3c5d7e', "tag:url:"+window.location.pathname]
disable_contact_button: true, // Type: Bool. disable the contact button completely, regardless of live chat integrations
disable_authorship: true, // disable authorship (faces/names) on articles and suggestions
shared_password: 'fluffyeggbaskets', // Type: String. Include your shared password so the user can open articles in a tab.
i18n: { // Change the value of the strings we use inside Lighthouse for internationalization
contact_button: 'Contact',
contact_name_placeholder: 'Jane Doe',
contact_email_placeholder: '',
contact_message_placeholder: 'I need help with...',
contact_submit: 'Send',
search_placeholder: 'Find articles...',
view_all: 'View All',
suggested_articles: 'Suggested Articles'
user: { // Prefill contact form submission values
name: 'Jane Doe',
email: ''
All these values need to be customized. You can't use the snippet above as-is 👆


Methods are ways to trigger a change in Lighthouse's state. For instance, to navigate to a piece of content, or to open the widget. These can be called from anywhere in your app, but be sure to check that Lighthouse is loaded successfully first.

All methods are available on the window.Lighthouse variable. So you'd call e.g. window.Lighthouse.hideButton() to hide the button completely from the user.

Method Name




Collapse the main Lighthouse panel



Show the main Lighthouse panel;


Hide the actual Lighthouse button completely



Show the Lighthouse button again


navigate(page, id?)

Open the main Lighthouse panel if you need, and navigate to a specific page



Lighthouse.navigate('article', 'abcde12345');

Lighthouse.navigate('category', '12345abcde');



Reload the config values and refresh Lighthouse


You can trigger Lighthouse methods from a hyperlink in your app. e.g. to head to an article, you can have a link like <a href="#" onclick="Lighthouse.navigate('article', '12a45b78');">Click here</a>


Callbacks tell your code when something's happened in Lighthouse, be it from a user action or from a method being triggered. The most common callback would be onReady(), to check when Lighthouse is ready to roll.

window.hdlh = {
..., // the rest of your widget config would replace the ... here, e.g. your widget_key
onLoad: function () {}, // fires when Lighthouse has loaded all data from the server
onReady: function () {}, // fires when the Lighthouse API is ready for use
onShow: function () {}, // fires when the main Lighthouse panel is shown
onHide: function () {}, // fires when the main Lighthouse panel is hidden
onButtonShow: function () {}, // fires when the Lighthouse button is shown
onButtonHide: function () {}, // fires when the Lighthouse button is hidden
onNavigate: function (data) {
/* fires when Lighthouse navigates to a new page
* data = {
* page: 'suggestions|home|contact|article|category',
* category_id: '', // category_id of the category or article that's being navigated to
* article_id: '' // article_id of the article that's being navigated to
* }
onSearch: function (data) {
/* fires when someone performs a search in Lighthouse
* Note: Lighthouse uses realtime search, so this could be fired
* up to once every 500ms
* data = {
* query: '', // the query these results are for
* results: [{title: '', href: '', ...}, ...] // array of articles that were found for this query
* }
onContactFormSubmit: function (data) {
/* fires when someone submits a contact form
* data = {
* name: '', // the name that was submitted
* email: '', // the email that was submitted
* message: '' // the message that was submitted
* }

Reloading Lighthouse

When you make changes to config on the fly, for example in a single page app, you'll need to reload Lighthouse for those changes to take effect.

Reloads are instant and maintain internal state, so it's safe to do these often. Use the reload() method to apply your new config after making the change to window.hdlh.

What did you think of this doc?

Understanding Lighthouse

Get in touch

This site is protected by hCaptcha and its Privacy Policy and Terms of Service apply.