# Widgets

> Live searches and views on the board, whose permissions they run with, and when they refresh.

Widgets are live views on the board: searches and summaries that keep themselves up to date, and whose rows you can drag out as cards.

![Three widgets: a review queue of pull requests waiting for review, a milestone with a progress ring and burn-up chart, and a stale finder grouping quiet items by age.](https://tack.social/_astro/tracking-light.BGGt7VCg_cft4K.webp)

A review queue, a milestone and a stale finder.

[List](https://tack.social/widgets/list.md)Any search, kept live.

[Timeline](https://tack.social/widgets/timeline.md)What was opened, closed or merged between two dates.

[Release draft](https://tack.social/widgets/release-draft.md)What's merged since the last release, as notes.

[Dependency map](https://tack.social/widgets/dependency-map.md)What blocks what: the critical path, and cycles.

[Review queue](https://tack.social/widgets/review-queue.md)Pull requests waiting for review, oldest first.

[Milestone](https://tack.social/widgets/milestone.md)Progress, burn-up, due date, and what's at risk.

[Stale finder](https://tack.social/widgets/stale-finder.md)Items gone quiet, with quick ways to tidy them.

[Custom widgets](https://tack.social/widgets/custom.md)Your own code, in a sandbox, drawing the board's data. Off unless the owner allows them.

## Adding a widget

Press `W` (or **Widget** in the toolbar) to open the picker. Click a kind to add it in the nearest free space to the middle of the view, so it doesn’t land on top of what’s there, or drag it onto the board to put it exactly where you drop it. Clicking the board with the widget tool adds a blank list there.

Where the instance has [AI](https://tack.social/boards/ai.md) on, you can describe the widget you want instead, in **Ask for one** at the top of the picker: it’s set up for you and previewed, live, before you place it.

The picker also has **Quick lists for owner/name**, searches over the board’s busiest repository (the one with the most cards): “Open bugs”, “Needs triage”, “Open pull requests”, “Good first issues”, “Unanswered questions” (the repository’s discussions waiting for an answer), “Top ideas” (its most upvoted ideas, when it has an Ideas category; “Top discussions” otherwise), “Recent announcements” (when it has an Announcements category), “Assigned to me” and “My review queue”. Inboxes and rules offer the same searches under the same names, except “Top ideas” and “Top discussions”, which are only an order.

A board is shared, so when you’re signed in, “Assigned to me” and “My review queue” are added for you by name (“Assigned to alice”, `assignee:alice`): everyone sees the same list when you say “look at the review queue”. A widget that still searches `@me` shows each person their own results, and says so with a **Your view** badge.

## Configuring and resizing

The gear in a widget’s header opens its settings beside it, on whichever side has room, and kept on screen. The panel helps with the search: one in plain words, or one with no repository, gets a suggestion of what it probably meant (“Did you mean `repo:acme/unpic label:bug`?”, from the board’s repository and its labels), one click to use. A **Forge** choice only appears when the board has items on more than one. Searches and text apply when you press `Enter` or leave the field, since each change runs the widget’s searches again for everyone. Settings changes are undoable, like any other edit. **Done** or `Esc` closes the panel.

Select a widget to resize it from its edges and corners (at least 260 × 200). Pick it up by its header to move it. Zoomed out, each widget shows one big number.

Every setting of every kind is in its reference page, generated from the widget’s schema.

## Whose permissions

**A widget’s searches run as whoever’s looking at it.** Two people looking at the same widget can see different rows.

- **Signed in**: searches run with your own GitHub account, so you see exactly what you could see on GitHub, private repositories included, and `@me` means you. Your results only go to you.
- **Not signed in** (on a public board): searches only look at public repositories (Tack adds `is:public`), and anything not known to be public is dropped. `@me` means nothing: “Sign in to see what “@me” means for you.”

## When widgets refresh

- **On a schedule**, while anyone has the widget on screen: every 5 minutes for lists, timelines, review queues, milestones and custom widgets; every 10 for release drafts and dependency maps; every 15 for stale finders.
- **When GitHub says something changed** in a repository a widget searches (or whose items it’s showing), from the [app’s webhooks](https://tack.social/self-hosting/repositories.md). Searches with no `repo:`, `org:` or `user:` run again on any delivery the board hears about. These refreshes wait a couple of seconds for more news, and never run a search more than once every ten seconds. Repositories without the app send no webhooks, so widgets over them refresh on the schedule.
- **When you ask**: the header’s **Refresh**.
- **When its settings change**.

Results are shared: two tabs, or two widgets with the same search, cost one search. If a refresh fails, the widget keeps showing what it had: “Updated 10 min ago · couldn’t refresh”, with **Retry**.

GitHub limits how often anyone can search, so each board keeps well inside: at most 20 searches and 60 other reads a minute for each person (people who aren’t signed in share one allowance). If a board needs more, its widgets wait: “Lots of searches on this board just now: trying again in a moment.” If GitHub itself says to slow down, the widget says when it’ll try again.

GitHub only searches up to 256 characters, and Tack adds a sort (and `is:public` for people who aren’t signed in), so keep searches comfortably shorter than that.

## Rows and cards

Rows in every widget drag out onto the board as cards, or click one (or press Enter on it) to put its card beside the widget. The row stays, and the card remembers it came from the widget (see [Where cards come from](https://tack.social/automation/provenance.md)). A pin marks rows whose item is already on the board; point at a row and its card lights up, and the other way round.
