> For the complete documentation index, see [llms.txt](https://developers.frill.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.frill.co/frill-script/widgets/controlling-the-widget.md).

# Controlling the Widget

### Methods

Once you have [access to a Widget instance](/frill-script/widgets.md#frill-widget) there are methods you can use to control it.

#### `widget.open()`

Open the Widget.

#### `widget.close()`

Close the Widget.

#### `widget.toggle()`

Toggle (open/close) the Widget.

#### `widget.destroy()`

Destroy the Widget and remove it from the DOM.

#### `widget.viewSection(section: 'ideas' | 'roadmap' | 'announcements')` 

Route the Widget to a section.

#### `widget.viewAnnouncement(announcementSlug: string)` 

Route to an Announcement in the Widget. The `announcementSlug` can be found in the URL from the Announcement page.

#### `widget.viewIdea(ideaSlug: string)` 

Route to an Idea in the Widget. The `ideaSlug` can be found in the URL from the Idea page.

#### `widget.createIdea(defaultValues?: { name?: string, topics?: string[] })` 

Route the Widget to the Create Idea form. Accepts an optional default values object for the Idea name and topics. Topic IDs can be found in the URL if you filter your Ideas board in the platform.

#### `widget.setBadgeCount(count: number)` 

Set the [Widget Launcher badge](#user-content-fn-1)[^1] count. If 0 the badge will be removed.

### Events & Callbacks

The Widget will emit different events that you can subscribe to. You can subscribe to events when you call the `widget` method, or use the `widget.events.on` function once you have the Widget instance.

Callbacks are defined by:

```typescript
type FrillWidgetCallbacks = {
  /**
   * Fired when the Widget is ready and Announcements have loaded
   * widget.events.on('ready', () => {})
   */
  onReady(widget: FrillWidget) {},
  /**
   * Fired after the Widget has been opened
   * widget.events.on('open', () => {})
   */
  onOpen() {},
  /**
   * Fired after the Widget has been closed
   * widget.events.on('close', () => {})
   */
  onClose() {},
  /**
   * Fired when the Widget is destroyed
   * widget.events.on('destroy', () => {})
   */
  onDestroy() {},
  /**
   * Fired when a user logs in
   * widget.events.on('login', () => {})
   */
  onLogin(event: { user: { name: string; email: string } }) {},
  /**
   * Fired when a user logs out
   * widget.events.on('logout', () => {})
   */
  onLogout() {},
  /**
   * Fired after the badge count changes
   * widget.events.on('badgeCount', () => {})
   */
  onBadgeCount(event: {
    announcements: { idx: string; slug: string; published_at: string }[];
    count: number;
  }) {},
  /**
   * Fired after a boosted Announcement notification has been opened
   * widget.events.on('notificationOpen', () => {})
   */
  onNotificationOpen() {},
  /**
   * Fired after a boosted Announcement notification has been closed
   * widget.events.on('notificationClose', () => {})
   */
  onNotificationClose() {},
};

```

Here's an example of how you would subscribe to the `onBadgeCount` event.

```typescript
const widget = await window.Frill('widget', {
  key: 'YOUR_WIDGET_KEY', // <-- Add Widget key here
  callbacks: {
    // Add callback functions here, e.g.
    onBadgeCount({ count }) {
      console.log(`Widget has ${count} unread Announcements`);
    }
  },
});
```

Or you can use `widget.events` to subscribe/unsubscribe at any time:

```typescript
const unsubscribe = widget.events.on('badgeCount', () => {
  console.log(`Widget has ${count} unread Announcements`);
});
```

[^1]: The Widget Launcher is the button (Floating, Tab or Custom) that launches the Widget.