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

# Use the widget

> useHotglue React hook reference

# Description

The `useHotglue` is the primary way of using the `@hotglue/widget` package outside of the inline `Connections` component. Use this to launch the widget and access utility functions.

## Usage

First you must include the `HotglueConfig` provider as a higher order component in your React app. For example, in `index.js`:

```javascript index.js theme={null}

import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
import HotglueConfig from '@hotglue/widget';

ReactDOM.render(
  <HotglueConfig
    config={{
      apiKey: 'your-public-environment-api-key',
      envId: 'your-env-id'
    }}
  >
    <App />
  </HotglueConfig>,
  document.getElementById('root')
);
```

Then you can use the `useHotglue` hook anywhere, as shown below:

```javascript App.js theme={null}

import { Connections } from '@hotglue/widget';

const App = (props) => {
   const { openWidget } = useHotglue();

  return (
    <div>
        <button onClick={() => openWidget('test-user')}>Open</button>
    </div>
  );
};

export default App;

```

# Functions

Below is a reference of all of the currently supported functions from the `useHotglue` hook.

***

## openWidget

Opens the widget for a user with options.

### Usage

`HotGlue.openWidget(user id, options)`

### Parameters

| Name    | Type      | Description                                             |
| ------- | --------- | ------------------------------------------------------- |
| user id | `string`  | ID of current user of your application.                 |
| options | `objects` | [option](https://docs.hotglue.com/docs/options) objects |

***

## link

### Usage

`HotGlue.link(user id, flow id, source, preloaded, options)`

### Parameters

| Name      | Type      | Description                                                                                                                                          |
| --------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| user id   | `string`  | ID of current user of your application.                                                                                                              |
| flow id   | `string`  | ID of flow you wish to connect. Every flow in hotglue has an ID which can be found from the admin panel or API. source                               |
| source    | `string`  | ID of source you wish to connect – typically just the name of the source in lowercase. Full catalog is accessible via API. Ex. `salesforce`          |
| preloaded | `boolean` | Mark this flag as `true` if you used the `HotGlue.preload` function to improve load time. Defaults to `false`                                        |
| options   | `object`  | Object containing options to configure the form: `json { "helperText": "Need help finding credentials? [Read the docs](https://docs.hotglue.xyz)" }` |

### Description

If specified `source` is **not linked**, this will open a popup window for user to login
If specified `source` is **linked**, this will open the hotglue widget under specified flow so user can manage the source.

***

## reconnect

### Usage

`HotGlue.reconnect(user id, flow id, entity id, options)`

### Parameters

| Name      | Type     | Description                                                                                                                                           |
| --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| user id   | `string` | ID of current user of your application.                                                                                                               |
| flow id   | `string` | ID of flow you wish to reconnect. Every flow in hotglue has an ID which can be found from the admin panel or API. source                              |
| entity id | `string` | ID of source or target you wish to connect – typically just the name of the source in lowercase. Full catalog is accessible via API. Ex. `salesforce` |
| options   | `object` | Object containing options to configure the form: `json { "isTarget": false }`                                                                         |

### Description

Used to reconnect an OAuth entities. Note for non-OAuth sources or targets, this will have no effect. In order to reconnect a target, you must pass the `isTarget` parameter to the `options` object.

***

## disconnect

### Usage

`HotGlue.disconnect(user id, flow id, entity id, options)`

### Parameters

| Name      | Type     | Description                                                                                                                                              |
| --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| user id   | `string` | ID of current user of your application.                                                                                                                  |
| flow id   | `string` | ID of flow you wish to disconnect. Every flow in hotglue has an ID which can be found from the admin panel or API.                                       |
| source    |          |                                                                                                                                                          |
| entity id | `string` | ID of source or target you wish to disconnect – typically just the name of the source in lowercase. Full catalog is accessible via API. Ex. `salesforce` |
| options   | `object` | Object containing options to configure the form: `json { "isTarget": false }`                                                                            |

### Description

Used to disconnect an entity (source or target). Note you must pass the `isTarget` parameter to the `options` object if disconnecting a linked target.

***

## setListener

### Usage

`HotGlue.setListener(listener)`

### Parameters

| Name     | Type     | Description                                                                                                                                                                                               |
| -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| listener | `object` | Object containing all listeners. See list of available events [here](/connection-methods/embedded-widget/options/listener). ex. `{onSourceLinked: (source, flow) => console.log(JSON.stringify(source))}` |

## Description

Updates current listener configuration to specified listener object

***

## createJob

### Usage

`HotGlue.createJob(flowId, tenantId, startDate)`

### Parameters

| Name        | Type                | Required | Description                                                                  |
| ----------- | ------------------- | -------- | ---------------------------------------------------------------------------- |
| `flowId`    | `string`            | Yes      | ID of flow                                                                   |
| `tenantId`  | `string`            | Yes      | ID of user                                                                   |
| `startDate` | `string` (ISO date) | No       | Optional. Used to override start date of the job. ex: `2022-10-16T00:00:00Z` |

### Response

<Warning>
  Returns a Promise which must be awaited or assigned a callback to extract relevant data
</Warning>

```json JSON theme={null}
{
    "job_id": "lmaEbA",
    "env_id": "dev.example-env.hotglue.xyz",
    "job_name": "test_job:_V-vgdlLN",
    "tenant": "default",
    "started_by": "default",
    "flow": "l8odS2mce",
    "s3_root": "default/flows/l8odS2mce/jobs/lmaEbA",
    "start_time": "2020-12-30T18:01:01.828266+00:00",
    "state": {},
    "tap": "quickbooks:sandbox",
    "status": "ETL_FAILED",
    "message": "ETL error...",
    "last_updated": "2020-12-30T20:31:00.081282+00:00"
}
```

### Description

Convenience function wrapping the hotglue API to run a job for the user.

## close()

### Usage

```js theme={null}

const { link, close } = useHotglue()

function onClick() {
  link(tenantId, flowId, sourceId, false, {
    hideBackButtons: true,
    listener: {
      onSourceLinked: () => {
        close();
      }
    }
  })
}

```

### Description

Closes the hotglue widget.

## setOptions

### Usage

```js theme={null}
const { setOptions } = useHotglue()

setOptions({
  hideBackButtons: true,
  listener: {
    onSourceLinked: (source, flow) => console.log('Source linked!')
  }
})
```

### Parameters

| Name    | Type      | Description                                                                                                                                  |
| ------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| options | `Options` | Object containing widget configuration options. See [available options](/connection-methods/embedded-widget/options) for complete reference. |

### Description

Updates the current widget configuration with new options. This function allows you to widget behavior globally. The options object can contain any of the supported widget configuration parameters.

### Available Options

The `options` parameter accepts an object with the following properties:

| Option               | Type       | Description                                                                                                                           |
| -------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `hideBackButtons`    | `boolean`  | Hides back buttons in the widget. Useful for preventing users from navigating away from specific flows.                               |
| `listener`           | `object`   | Object containing event listeners. See [listener options](/connection-methods/embedded-widget/options/listener) for available events. |
| `multipleSources`    | `boolean`  | Allows tenants to connect multiple distinct connectors in the same flow.                                                              |
| `flow`               | `string`   | Opens the widget directly to a specific flow instead of showing the flow list.                                                        |
| `flowFilter`         | `function` | Function to filter which flows are displayed.                                                                                         |
| `localization`       | `object`   | Object containing text overrides for widget UI elements.                                                                              |
| `createMetadata`     | `object`   | Object containing metadata to be created with new connections.                                                                        |
| `customFieldMapping` | `object`   | Object containing custom field mapping configuration.                                                                                 |

### Example

```js theme={null}
const { setOptions, openWidget } = useHotglue()

// Configure widget options
setOptions({
  hideBackButtons: true,
  multipleSources: true,
  flow: "h8Dksj2",
  listener: {
    onSourceLinked: (source, flowId, tenantId) => {
      console.log(`Source ${source.name} linked to flow ${flowId}`)
    },
    onWidgetClose: () => {
      console.log('Widget closed')
    }
  },
  localization: {
    startingScreen: {
      header: "Connect Your Data",
      subtitle: "Choose your integration below"
    }
  }
})

// Open widget with the configured options
openWidget('user-123')
```

***

## setSchema

### Usage

```js theme={null}
import { useHotglue } from '@hotglue/widget'

const { setSchema, openWidget } = useHotglue()

const schemas = [
  {
    flowId: 'flow_123',
    schema: [
      {
        table: 'Leads',
        fields: [
          { id: 'first_name', name: 'First Name' },
          { id: 'last_name', name: 'Last Name' },
          { id: 'email', name: 'Email' }
        ]
      }
    ]
  }
]

setSchema(schemas, { enforceOneToOneMapping: true })
openWidget('user-123')
```

### Parameters

| Name      | Type            | Description                                                                                                                        |
| --------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `schemas` | `Array<Schema>` | Array of flow-level schema definitions. Each item includes `flowId` and a `schema` array with `table` and `fields` (`id`, `name`). |
| `options` | `SchemaOptions` | Optional behavior overrides for mapping. Currently supports `enforceOneToOneMapping` (`boolean`).                                  |

### Description

Enables the custom mapping component and sets the source schema for the widget at runtime when using `@hotglue/widget` in React. Use this to define the fields your users map from before opening the widget.

When `enforceOneToOneMapping` is `true`, each source field can only map to one target field, preventing duplicate mappings in the UI.

For full schema structure details, see [custom field mapping](/connection-methods/embedded-widget/options/custom-field-mapping).

***