--- title: "Progress" description: "Bar / ring percentage. What the progress is for, the data it needs and every option it has." section: "Widgets" canonical: "https://banksync.io/docs/widgets/chart-progress" specs: ["dashboards"] operationBindings: [{"capability":"dashboards","operation":"dashboards.author"}] --- Bar / ring percentage. It sits in the **Single value** group of the widget library. ![Example progress on a BankSync dashboard](https://cdn.banksync.io/screenshots/docs/charts/progress.cc31ddd5dd807b02.png) ## When to use it Use progress to show one value as a share of a maximum, as a ring, half ring or bar. For example, show how much of a savings goal is reached, how much of the monthly budget is spent, or how many transactions have been categorised. ## When to pick something else - A value against a target and ranges on a scale? Use a **Meter**. - A dial with good, warning and bad zones? Use a **Gauge**. - The number itself, with its change? Use a **KPI**. - Several goals side by side? Use a **Bullet chart**. ## The data it needs Pick these in the **Data** tab of the inspector. BankSync suggests a column for each when your source has an obvious match. | Field | Needed | Pick | Notes | | --------- | ------ | -------- | ----- | | **Value** | Yes | a number | | Each row is drawn as it is, so shape the rows first if you need totals. See [Shaping data](/docs/dashboards/dashboards-shaping-data). ## Progress options Set these on the **Style** tab of the inspector. "Automatic" means BankSync picks a value from the chart's size and data. | Option | What it does | Values | New charts start with | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | --------------------- | | **Value column** | The column the number comes from. Its values are added up into one number. | Text | `value` | | **Maximum** | The value that counts as 100%: a number, or a column of the rows such as a budget. | Number | 100 | | **Pace marker** | A tick on the track showing where you should be by now, as a fraction of the maximum (0.5 is halfway). | Number, 0 to 1 | Automatic | | **Good direction** | Whether filling the bar is good news. More is better for a goal or a savings target (green when reached); less is better for a budget (amber near the limit, red past it), the default. | More is better, Less is better | Automatic | | **Shape** | A bar, a ring, or a bar split into segments. Leave empty to pick a bar on wide cards and a ring otherwise. | Bar, Ring, Segments | Automatic | | **Orientation** | Lay the bar horizontally or vertically. Vertical picks a bar unless you choose another shape. | Horizontal, Vertical | Automatic | | **Corner radius** | Rounds the ends of the bar or ring, in pixels. 0 gives square ends. | Number, 0 or more | Automatic | | **Thickness** | Thickness of the bar or ring, in pixels. | Number, 0 or more | Automatic | | **Show percentage** | Write how far along the value is, as a percentage. On by default. | On or off | Automatic | | **Show value** | Also write the value and the maximum, such as "$450 of $1,000". | On or off | Automatic | | **Segments** | Split the bar or ring into this many blocks (2 to 60). The segments shape uses 10 when empty. | Whole number, 0 to 9007199254740991 | Automatic | ### Needs history Show a note instead of the chart until the rows cover enough periods, so a first week never reads as a trend. | Option | What it does | Values | New charts start with | | ------------------- | ---------------------------------------------------------------------------------- | ------------------------------- | --------------------- | | **Date field** | The date column whose distinct periods are counted. | Text | Automatic | | **Period** | What counts as one period: a day, week, month, quarter or year. | Day, Week, Month, Quarter, Year | Automatic | | **Periods needed** | How many distinct periods the rows must cover before the chart draws (2 to 60). | Whole number, 2 to 60 | Automatic | | **Waiting message** | Shown until there is enough history. Leave empty for a message naming the periods. | Text, up to 120 characters | Automatic | ### Number format How the number is written: currency, percent, decimals and locale. | Option | What it does | Values | New charts start with | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | --------------------- | | **Format** | The kind of number: plain, currency, percent, accounting, scientific, compact (1.2K), date, time or duration. Percent expects a fraction, so 0.25 shows 25%. | Number, Currency, Percent, Accounting, Scientific, Compact, Date, Time, Duration | Automatic | | **Locale** | Language and region for separators and symbols, such as en-US or en-AU. Defaults to en-US. | Text | Automatic | | **Currency** | Three-letter currency code such as USD, AUD or EUR, or auto to use the currency most of the rows are in. Defaults to USD when neither this nor a currency column is set. | Text | Automatic | | **Currency column** | The column that holds each row’s currency code, such as currency or isoCurrencyCode, for money in more than one currency. A total is shown in the currency most of its rows are in; when they mix currencies the code is written after the number, such as 1,234.50 AUD, and a KPI says the total adds different currencies. With no code in the rows, a plain number is shown rather than a guessed symbol. | Text, up to 120 characters | Automatic | | **Currency display** | Write the currency as its symbol, such as A$1,234.50 (the default), as its code after the number, such as 1,234.50 AUD, which reads the same in every country, or as the bare sign, such as $1,234.50. A dashboard whose money is all in its workspace’s currency uses the bare sign on its own. | Symbol, Code, Narrow | Automatic | | **Decimal places** | Show exactly this many digits after the decimal point. | Number | Automatic | | **Sign** | When to show a plus or minus sign: automatically, always, for non-zero values only, or never. | Auto, Always, Except zero, Never | Automatic | | **Time zone** | Time zone for date and time formats, such as Australia/Sydney. Leave empty for the viewer’s own. | Text | Automatic | ### Colour steps Colours the fill changes to as the value grows. Named steps are marked on the track. Add as many as you need; each one has: | Option | What it does | Values | New charts start with | | --------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------- | --------------------- | | **Starts at** | Where this step starts, as a fraction of the maximum (0.8 is 80%). The fill takes the colour of the highest step reached. | Number, 0 or more | Automatic | | **Step colour** | Colour of the fill once the value reaches this step. | Colour | Automatic | | **Step name** | Optional name; a named step gets a tick across the track. | Text | Automatic | ## Shared chart styling Every chart also has the shared styling options. These apply to this one: - [Legend](/docs/widgets/chart-styling#legend): position, layout and which series show. - [Axes](/docs/widgets/chart-styling#axes): titles, tick labels and number format. - [Grid](/docs/widgets/chart-styling#grid), [title](/docs/widgets/chart-styling#title), [padding](/docs/widgets/chart-styling#padding) and [background](/docs/widgets/chart-styling#background). - [Value labels](/docs/widgets/chart-styling#value-labels) on the marks. - [Categories and labels](/docs/widgets/chart-styling#categories-and-labels): top N with "Other", sort order, readable labels, the handwritten callout. - [Style](/docs/widgets/chart-styling#style): corner radius, line width, opacity and animation. - [Tooltip](/docs/widgets/chart-styling#tooltip) on hover. - [Colours](/docs/widgets/chart-styling#palette): follow the dashboard palette or pick one for this chart. ## Messy data - All rows are added into one value by default. - With no matching rows it shows 0%, not an empty message. - The maximum defaults to 100. A maximum of zero or below shows "Set a maximum above 0". - A value past the maximum fills the mark, keeps the true percent (for example "172%") and adds an "over" marker. A negative value leaves the mark empty while the percent stays negative. ## On a phone Unless you choose a shape, a wide and short cell gets a bar and a squarer cell gets a ring. On phones the cell is fairly square, so you usually get a ring; choose the bar shape if you want a thin strip. ## Related charts - [Gauge](/docs/widgets/chart-gauge): Needle on a band scale - [Meter](/docs/widgets/chart-meter): Bar against a target