# `useProgress` / `useProgressGroup`

## `useProgress`

### Arguments

| Argument  | Type                       | Required | Description        |
| --------- | -------------------------- | :------: | ------------------ |
| `current` | `MaybeRefOrGetter<number>` |    ✓     | The current value. |
| `total`   | `MaybeRefOrGetter<number>` |    ✓     | The total value.   |

### Returns

| Property        | Type                      | Description                                                |
| --------------- | ------------------------- | ---------------------------------------------------------- |
| `current`       | `ComputedRef<number>`     | The normalized `current` input                             |
| `total`         | `ComputedRef<number>`     | The normalized `total` input                               |
| `fillWidth`     | `ComputedRef<${number}%>` | The width of the progress bar to be filled (e.g. `"35%"`). |
| `percentage`    | `ComputedRef<number>`     | The percentage between `current` and `total`.              |
| `percentageCap` | `number`                  | The percentage cap of the progress bar. (see below)        |

`percentageCap` is the `percentage` rounded up to the nearest hundred.

For example, if `current` is `15` and `total` is `10`, then `percentage` will be `150` and `percentageCap` will be `200`.

`fillWidth` is the percentage of the progress bar to be filled.

In the example above, `fillWidth` will be `"75%"` (`150` / `200` = `0.75`).

```ts
const { fillWidth, percentage, percentageCap } = useProgress(current, total)

// current = 15; total = 60
// → percentage = 25
// → percentageCap = 100
// → fillWidth = '25%'

// current = 90; total = 60
// → percentage = 150
// → percentageCap = 200
// → fillWidth = '75%'
```

## `useProgressGroup`

This composable will allow handling multiple progress bars and normalize their fill width across all of them.

### Arguments

| Argument  | Type                                                | Required | Description                                                                                                              |
| --------- | --------------------------------------------------- | :------: | ------------------------------------------------------------------------------------------------------------------------ |
| `sources` | `MaybeRefOrGetter<T[]>`                             |    ✓     | The sources array                                                                                                        |
| `fn`      | `(source: T) => { current: number; total: number }` |    ~     | Returns `current` and `total` for each `source`. If `source` already has these properties, this argument can be omitted. |
| `options` | `{ sort?: 'asc' \| 'desc' }                         |          | Whether to sort the progress items                                                                                       |

### Returns

| Property               | Type                                                      | Description                                           |
| ---------------------- | --------------------------------------------------------- | ----------------------------------------------------- |
| `progressItems`        | `ComputedRef<Reactive<Progress & { source: TSource }>[]>` | The normalized progress items.                        |
| `highestPercentage`    | `ComputedRef<number>`                                     | The highest `percentage` among all progress items.    |
| `highestPercentageCap` | `ComputedRef<number>`                                     | The highest `percentageCap` among all progress items. |
