Sidecar

Please type the name of the public, existing room that you want to load into your sidecar. E.g. gitterHQ/sidecar

Just copy and paste it into your site.

<script>
  ((window.gitter = {}).chat = {}).options = {
    room: ''
  };
</script>
<script src="https://sidecar.gitter.im/dist/sidecar.v1.js" async defer></script>
A little snippet in your website

Documentation

Overview

Primarily sidecar has an activation element that will show sidecar and a target element where sidecar gets loaded. These elements are specified by default but can be customised (see below).

UI Customisation

If you need a custom button or want to insert the chat in your own element, use the following setup:

  • Activation element: The "Open Chat" button
  • Target element: The wrapper element that the chat is embedded into
<script>
  ((window.gitter = {}).chat = {}).options = {
    room: 'gitterHQ/sidecar',
    activationElement: '.my-special-button',
    targetElement: '.my-special-target-element'
  };
</script>

Toggle Buttons

You can define toggle/open/close buttons in your page using the .js-gitter-toggle-chat-button class and an optional data-gitter-toggle-chat-state attribute. If you do not provide a data-gitter-toggle-chat-state, it will default to 'toggle'. See the examples/toggle-chat-class-buttons example.

<button class="js-gitter-toggle-chat-button">Toggle Chat</button>
<button class="js-gitter-toggle-chat-button" data-gitter-toggle-chat-state="true">Open Chat</button>
<button class="js-gitter-toggle-chat-button" data-gitter-toggle-chat-state="false">Close Chat</button>

Examples

Options

Set options with the global window option:

<script>
  ((window.gitter = {}).chat = {}).options = {
    room: 'gitterHQ/sidecar'
  };
</script>

You can also override these options individually on the target element:

<div
  class="gitter-chat-embed"
  data-room="gitterHQ/sidecar"
></div>
  • options.room: string - This is the Gitter room that sidecar will load (gitterHQ/sidecar)
    • Acceptable values: string
    • Default: undefined
  • options.targetElement: Where you want to embed the chat.
    • Acceptable values: Dom node, array of dom nodes, or a string selector
    • Default: Elements that match '.gitter-chat-embed'
  • options.activationElement: When options.showChatByDefault is false, this is the element you have to click/interact with to get the chat to actually embed, "Open Chat" button.
    • Acceptable values: Dom node, array of dom nodes, a string selector, or boolean
    • Default: undefined
    • Note: This will automatically get generated if you don't specify it (undefined, or true)
      • Note: Passing in false or null will disable the activation element
  • options.showChatByDefault: Whether to embed the chat on page load(true) or wait until the options.activation is resolved/clicked/interacted with(false).
    • Acceptable values: boolean
    • Default: false
    • Note: Use with caution, useful for use cases where you have a page dedicated to chat.
  • options.useStyles: This will embed CSS into your document to style the activation and target element. If you want to customise these, set this option to false and specify your own CSS.
    • Acceptable values: boolean
    • Default: true
  • preload: Whether the Gitter chat iframe should be loaded in when the chat embed instance is created(this is the page load for default embed)
    • Acceptable values: boolean
    • Default: false

Window Options:

You can set any of the chat options above in this object as well

  • window.gitter.chat.options.disableDefaultChat: Stop the default chat from loading on the page when including the Sidecar script. So you can handle the Gitter chat creation yourself.
    • The default chat is stored on window.gitter.chat.defaultChat.

API

gitter.Chat

var chat = new window.gitter.Chat(/* options */);`
  • options (getter): Get a readable copy of the options used for this chat instance
  • toggleChat(isChatOpen): Function/method - Takes a boolean which toggles the visibility of the chat panel
    • This can be used an explicit show/hide method by passing in a explict show(true) or hide(false) boolean.
  • destroy(): Function/method - Clean-up and remove any elements created by the embed

Events

Emitted on Document:

  • gitter-sidecar-ready: Emitted when the sidecar script has loaded and is available via window.gitter
  • gitter-sidecar-instance-started: Emitted after any Sidecar chat instance has initialized
    • Data: chat: The sidecar chat instance that was initialized

Emitted on Target Element:

  • gitter-chat-toggle: Emitted whenever the chat is opened or closed
    • Data: state: Whether it was opened(true) or closed(false)
  • gitter-chat-started: Emitted after the Sidecar chat instance has initialized
    • Data: chat: The sidecar chat instance that was initialized

example:

document.querySelector('.gitter-chat-embed').addEventListener('gitter-chat-toggle', function(e) {
  console.log(e.detail.state ? 'Chat Opened' : 'Chat Closed');
});

Add some Gitter to your site

Sidecar is a (mostly) code-free way of embedding Gitter into your website with a simple JavaScript snippet.

It works out of the box with no customization, or you can control its behaviour with some basic configuration.