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

# Widgets

> Add widgets to a dashboard, choose a chart, group your data, and filter it.

A widget is a single chart of a single metric, sitting in one cell of the dashboard grid. A dashboard is just a collection of widgets you arrange yourself.

## Add a widget

Select **Add widget** to open the widget builder. It has two tabs:

* **Recommendations** - ready-made widgets you can drop in and tweak.
* **Metrics** - build a widget from scratch.

<Tip>
  On an empty dashboard, a shortlist of **recommended templates** appears in
  place of the grid so you have a quick starting point.
</Tip>

## Start from a template

The **Recommendations** tab is a gallery of prebuilt widgets, each answering a common question - for example *Billability over time*, *Pipeline by stage*, or *Which projects have the most revenue from planned resources?* Search the gallery, pick one, adjust anything you like, and save. A template is just a starting configuration, so nothing is locked in.

## Build from a metric

On the **Metrics** tab, first pick a **metric** - the number you want to measure. Metrics are grouped by domain (Time, Budget, Revenue, Forecast, Profitability). See the [metric catalogue](/docs/dashboards/metric-catalogue) for the full list.

Then configure the widget:

<Steps>
  <Step title="Title">Optional. Defaults to the metric name.</Step>

  <Step title="Chart type">
    Only the chart types that suit the metric are offered: **Number**, **Line**,
    **Bar**, **Stacked bar**, **Area**, **Pie**, **Donut**, or **Table**.
  </Step>

  <Step title="Group by">
    Break the metric down by up to **two** dimensions - such as period, team,
    member, project, customer, project status, deal status, or billable. Which
    ones are available depends on the metric.
  </Step>

  <Step title="Segment">
    An optional second breakdown that splits each group (for example, hours by
    month, segmented by team). Not available for Number, Pie, or Donut charts.
  </Step>

  <Step title="Bucket by">
    When you group by **period**, choose the bucket size: day, week, month,
    quarter, or year.
  </Step>

  <Step title="Filters">
    Narrow this widget to specific customers, projects, teams, or members. The
    available filters depend on the metric.
  </Step>
</Steps>

The **preview** updates as you go. Save to drop the widget onto the grid.

### Chart type rules

* **Number** shows a single total for the whole date range.
* **Pie** and **Donut** take exactly one breakdown and no segment.
* The other charts accept one or two breakdowns.

## Manage widgets

Open a widget's menu to:

* **Edit** - reopen the builder.
* **Delete** - remove the widget.
* **Move up** / **Move down** - reorder it on the grid.
* **Size** - resize to **Small**, **Medium**, or **Large**.

You can also **expand** a widget to full screen, and **download** its data as a **CSV**.

<Card title="Metric catalogue" icon="list" iconType="regular" href="/docs/dashboards/metric-catalogue">
  Every metric you can chart, how it's calculated, and how you can break it
  down.
</Card>