> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget

> Integrate our capabilities into websites or other HTML-based applications.

The Genow Widget is a web component designed for embedding in websites. It allows you to bring Genow Agents directly to your end users.

> Note that the widget only shows one Agent. Users will only see the input field and the answer. An asset selection is not possible - the preselected assets will be taken into account. Guided search fields are not supported currently.

<Warning>
  Before you can use the widget, you must send Genow the URL of the page where the widget will be embedded. This is required so the widget can be correctly authorized for your domain. Without this step, the widget will not load correctly.
</Warning>

<Note>
  **Prerequisites**: Before you begin, ensure you have the required files provided by Genow: `vue.global.prod.js` (Vue 3 build), \
  `genow-widget.css` (styles), and \
  `genow-widget.umd.min.js` (minified UMD bundle with FontAwesome included)
</Note>

**To integrate the widget, you need to follow three main steps:**

1. Load the required resources (CSS, Vue3, UMD bundle - see above),
2. Add the custom element `<genow-widget>` to your HTML &
3. Configure authentication and attributes.

***

## (1) Basic Integration Steps

<Steps>
  <Step title="Load Resources" titleSize="h3">
    Include the CSS and JavaScript files in your HTML structure. You must load the widget CSS, the Vue 3 global build, and the Genow Widget UMD bundle.

    ```html theme={null}
    <link rel="stylesheet" href="[https://your-cdn.com/genow-widget.css](https://your-cdn.com/genow-widget.css)">

    <script src="[https://your-cdn.com/vue.global.prod.js](https://your-cdn.com/vue.global.prod.js)"></script>

    <script src="[https://your-cdn.com/genow-widget.umd.min.js](https://your-cdn.com/genow-widget.umd.min.js)"></script>
    ```
  </Step>

  <Step title="Add the Custom Element" titleSize="h3">
    Add the `<genow-widget>` custom element to your HTML where you want the widget to load. The widget is responsive and adapts to the container size, while overlays are shown over the whole screen.

    ```html theme={null}
    <genow-widget
      use-case-id="your-use-case-id"
      api-endpoint="[your-api.com/api](https://your-api.com/api)"
      auth-provider="your-provider"
      auth-token="your-token">
    </genow-widget>
    ```
  </Step>

  <Step title="Handle Authentication" titleSize="h3">
    The widget requires a valid authentication token to access your data.

    <Warning>
      **Token Management:** Tokens must be obtained from your authentication system. When a token expires, it must be refreshed, and the widget may need to be reloaded.
    </Warning>

    **Supported Authentication Methods:**

    * **Firebase** (email/password, Google SSO): use `auth-provider="Firebase"`
    * **Microsoft SSO** (EntraID/Azure AD): use `auth-provider="Microsoft"`
    * **Google SAML**: use `auth-provider="Genow"`

    **Implementation Example:** You can update the widget attributes dynamically via JavaScript after the user logs in.

    ```javascript theme={null}
    // After user logs in, get token
    const authToken = await getAccessToken(); // Your auth method

    // Set token on widget element
    const widget = document.querySelector('genow-widget');
    widget.setAttribute('auth-token', authToken);
    widget.setAttribute('auth-provider', 'Firebase'); // or 'Microsoft' / 'Genow'
    ```
  </Step>
</Steps>

***

## (2) Configuration and Attributes

You can configure the widget using HTML attributes. Dynamic updates to these attributes via JavaScript are supported.

### Required Attributes

| Attribute       | Description                              |
| :-------------- | :--------------------------------------- |
| `use-case-id`   | The ID of the Agent you want to display. |
| `api-endpoint`  | Your Genow API endpoint URL.             |
| `auth-provider` | The name of the authentication provider. |
| `auth-token`    | The current authentication token.        |

### Optional Attributes

| Attribute                      | Description                                                                         | Default            |
| :----------------------------- | :---------------------------------------------------------------------------------- | :----------------- |
| `selected-knowledge-asset-ids` | Comma-separated list (e.g., "asset1, asset2") of assets to query.                   | All default assets |
| `selected-thread-id`           | Pre-load a specific conversation thread.                                            | -                  |
| `threads-page-size`            | Number of threads to load.                                                          | 1                  |
| `llm`                          | LLM model name (e.g., "gemini-2.5-pro").                                            | -                  |
| `locale`                       | Language ("en" or "de").                                                            | "en"               |
| `environment`                  | "production" or "development".                                                      | "production"       |
| `use-shadow-dom`               | Encapsulates styles. Set to "false" if you want global styles to affect the widget. | "true"             |

***

## (3) Advanced Customization

<Tabs>
  <Tab title="Custom CSS">
    If `use-shadow-dom` is enabled (default), you must use the `custom-css` attribute to override styles. You can override specific CSS variables for theming.

    ```javascript theme={null}
    custom-css="
      #widget-root {
        --primary-color: #007bff;
        --primary-color-light: #00aaff;
        --primary-color-dark: #004cff;
      }
    "
    ```
  </Tab>

  <Tab title="Custom Translations">
    You can override default text by passing a JSON string to the `custom-translations` attribute.

    ```javascript theme={null}
    custom-translations='{
      "en": {
        "chat_search": {
           "initial": {
             "input_placeholder": "Ask the Genow Widget..."
           }
        }
      },
      "de": {
        "chat_search": {
           "initial": {
             "input_placeholder": "Frage das Genow Widget..."
           }
        }
      }
    }'
    ```
  </Tab>
</Tabs>

***

## Example

<Expandable title="full example">
  ```javascript theme={null}
      <link rel="stylesheet" href="https://your-cdn.com/genow-widget.css">
  <script src="https://your-cdn.com/vue.global.prod.js"></script>
  <script src="https://your-cdn.com/genow-widget.umd.min.js"></script>

  <genow-widget
    use-case-id="your-use-case-id"
    api-endpoint="your-api.com/api"
    auth-provider="your-provider"
    auth-token="your-token"
    use-shadow-dom="true"
    custom-css="
      #widget-root { 
        --primary-color: #007bff;
        --primary-color-light: #00aaff;
        --primary-color-dark: #004cff;
      }
    "
    custom-translations='{
      "en": {
        "chat_search": {
          "initial": {
            "input_placeholder": "Ask the Genow Widget..."
          }
        }
      },
      "de": {
        "chat_search": {
          "initial": {
            "input_placeholder": "Frage das Genow Widget..."
          }
        }
      }
    }'>
  </genow-widget>

  ```
</Expandable>

***

## Troubleshooting

<Info>
  **Browser Compatibility:** The widget supports modern browsers (Chrome, Firefox, Safari, Edge) and requires JavaScript to be enabled.
</Info>

If you encounter issues, please check the following:

* **Widget not loading:** Verify script paths for Vue and the UMD bundle.
* **Authentication errors:** Verify the validity of your token and that the provider name matches the backend configuration.
* **Styling conflicts:** If styles look wrong, try enabling Shadow DOM or adjusting your `custom-css`.
* **CORS errors:** Ensure your API endpoint allows requests from your domain.

For multiple widget instances on the same page, ensure each has its own configuration. They operate independently.