Skip to content
Documentation

    Widget Configuration

    The widget configuration controls the embedded experience independently of the content it displays. Set the project ID first, then choose placement, trigger behaviour, colour scheme, and the small details that help the widget fit into your product.

    Use the default trigger for a ready-made entry point, or provide your own selector when the widget should open from an existing button. Keep the configuration in one JSON script so the behaviour is easy to review and change with the rest of your integration.

    Configuration options

    Section titled “Configuration options”

    Customize your widget to match your brand and app design using the widget properties. Adjust the title, description, colors, positioning, and trigger settings according to your preferences.

    The properties are expressed in JSON format and contained in a script tag with the id="released-widget-props".

    <script type="application/json" id="released-widget-props">

    Widget Properties

    Section titled “Widget Properties”

    The following options are available. You only need to set a property when its default does not suit your integration.

    PropertyDescription
    idThe ID of the release notes project.
    positionThe position of the widget. Can be top-left, top-right, bottom-right, or bottom-left.
    titleThe title of the widget.
    subTitleThe subtitle of the widget.
    triggerA string specifying a css selector that determines which element on the page will open the dialog when clicked. For example #changelog-button. If not specified, a default trigger button will be rendered.
    badgeWhether to display a badge with the unread count. Can be true or false.
    colorSchemeThe color scheme to use for the widget. Can be system, dark, or light.
    zIndexThe z-index to use for the widget.
    themeA custom theme to use for the widget. See below for theme properties.
    attributesAllows for passing data-* attributes to the host container for the widget. For more details see the Attributes section below.

    Theme

    Section titled “Theme”
    PropertyDescription
    colorsAn object that defines the primary and secondary colors for the widget.
    primaryThe primary UI color. Can be hex, hsl, rgb, or css color name.
    secondaryThe secondary UI color. Can be hex, hsl, rgb, or css color name.

    Attributes

    Section titled “Attributes”

    Setting data attributes can be helpful to prevent unwanted interactions with 3rd party libraries. For example, to prevent scrolling issues when the Lenis library is used, you can add the data-lenis-prevent attribute to the host container.

    Example:

    {
      "id": "",
      "attributes": {
        "data-lenis-prevent": "",
      }
    }

    Results in:

    <div id="__released-widget-host" data-lenis-prevent="" ...></div>

    Default values

    Section titled “Default values”

    These values apply when a property is not explicitly defined. Start here when you are deciding which values actually need to be customised.

    {
      "id": "",
      "position": "bottom-right",
      "title": "What's New",
      "subTitle": "The latest updates and improvements.",
      "trigger": "#trigger",
      "badge": true,
      "colorScheme": "system",
      "theme": {
        "colors": {
          "primary": "#7c3aed",
          "secondary": "#e879f9"
        }
      },
      "zIndex": 10000
    }

    Installation

    Section titled “Installation”

    To add the widget to your website or app, copy the following code snippet into the <head> element. Replace the [PROJECT_ID] placeholder with the ID found in your widget configuration.

    <script type="application/json" id="released-widget-props">
      {
        "id": "[PROJECT_ID]",
        "title": "Changelog",
        "subTitle": "New updates and improvements.",
      }
    </script>
    <script src="https://embed.released.so/1/widget.js"></script>

    The above code snippet contains two script tags. The first tag contains the configuration properties for the widget, and the second tag loads the widget.

    The available configuration options are described in the following section.