# Custom Launcher

Open the chat widget from your own button or link using the JavaScript API.

Open the Foxchat widget from your own button or link instead of the default floating chat bubble. This is useful when the default launcher conflicts with your UI, or you want the chat trigger to be part of your navigation or page layout.

## Quick Start

Hide the default launcher and use a custom button:

```javascript
<script>
  window.FoxchatSettings = { hideLauncher: true };
</script>
<script src="https://foxchat.dev/widget.js" data-project-id="your-project-slug"></script>

<button onclick="window.Foxchat.open()">Chat with us</button>
```

## API Reference

### `window.Foxchat`

A global object exposed by the widget script with methods to control the chat window.

| Method        | Description                               |
|---------------|-------------------------------------------|
| `open()`     | Opens the chat window                     |
| `close()`    | Closes the chat window                    |
| `toggle()`   | Opens the chat window if closed, closes if open |

### `window.FoxchatSettings.hideLauncher`

| Field            | Type     | Default | Description                                        |
|------------------|----------|---------|----------------------------------------------------|
| `hideLauncher`   | `boolean`| `false` | Hides the default floating chat button              |

This field is part of the existing `window.FoxchatSettings` object — you can combine it with `name`, `email`, and `metadata` fields from the [Visitor Identity API](/content/docs/visitor-identity/index.html).

## Examples

### Basic — custom button

<button onclick="window.Foxchat.open()">Contact Support</button>
```

### Link in navigation

```javascript
<nav>
  <a href="#" onclick="event.preventDefault(); window.Foxchat.open()">Help</a>
</nav>
```

### Toggle button

```javascript
<button onclick="window.Foxchat.toggle()">Toggle Chat</button>
```

### React / SPA

```javascript
function ContactButton() {
  return (
    <button onClick={() => window.Foxchat?.open()}>
      Chat with us
    </button>
  );
}
```

> **Tip:** Use optional chaining (`window.Foxchat?.open()`) if your button might render before the widget script has loaded.

### Keep the default launcher

You don't have to hide the default launcher to use the API. If you omit `hideLauncher`, the floating chat bubble will still appear and the API methods will work alongside it:

```javascript
<script src="https://foxchat.dev/widget.js" data-project-id="your-project-slug"></script>

<!-- Both the default bubble and this button will open the widget -->
<button onclick="window.Foxchat.open()">Need help?</button>
```

## How It Works

1. The `window.Foxchat` object is created as soon as the widget script is parsed — before the DOM finishes loading
2. If you call `open()` before the widget's React app has mounted, the command is queued and executed automatically once the widget is ready
3. When `hideLauncher` is `true`, the floating chat button is removed from the page, but the chat window still renders when opened via the API.