# Progress

Bilah kemajuan berbasis elemen progress native dengan label, persentase, dan mode tak tentu.

- Kategori: Feedback
- Status: stable
- Registry: https://markas.jenderalcorp.com/r/progress.json
- CLI: `npx markasui@latest add progress`

## Kapan dipakai

Menampilkan kemajuan proses yang terukur seperti unggah berkas atau langkah onboarding.

- Biarkan value kosong bila durasi proses tidak diketahui
- Selalu beri label atau aria-label
- Untuk placeholder konten yang sedang dimuat gunakan Skeleton

## Kode

### Blade

Simpan di `resources/views/components/markas/progress.blade.php`. Tanpa dependensi tambahan.

```blade
@props([
    'value' => null,
    'max' => 100,
    'label' => null,
])

@php
    $wrapper = 'grid gap-1.5';
    $header = 'flex items-center justify-between gap-4 text-sm';
    $labelClass = 'font-medium text-ink';
    $valueClass = 'text-muted tabular-nums';
    $bar = 'block h-2 w-full appearance-none overflow-hidden rounded-full border-0 bg-subtle [&::-webkit-progress-bar]:bg-subtle [&::-webkit-progress-value]:rounded-full [&::-webkit-progress-value]:bg-primary [&::-webkit-progress-value]:transition-[width] [&::-webkit-progress-value]:duration-200 [&::-webkit-progress-value]:ease-out [&::-moz-progress-bar]:rounded-full [&::-moz-progress-bar]:bg-primary indeterminate:animate-pulse indeterminate:bg-primary/30 indeterminate:[&::-webkit-progress-bar]:bg-primary/30 motion-reduce:animate-none motion-reduce:[&::-webkit-progress-value]:transition-none';

    // Same id on every render, so Livewire's morph (which matches elements by id) keeps the element. Pass `id` to set it.
    $idKey = 'markas-progress|'.(isset($this) && $this instanceof \Livewire\Component ? $this->getId() : '').'|'.($attributes->get('wire:key') ?? $attributes->whereStartsWith('wire:model')->first() ?? $attributes->get('name')).'|';
    for ($idIndex = 0; $__env->hasRenderedOnce($idKey.$idIndex); $idIndex++);
    $__env->markAsRenderedOnce($idKey.$idIndex);
    $id = $attributes->get('id') ?? 'markas-progress-'.hash('xxh32', $idKey.$idIndex);
    $percent = $value === null ? null : (int) min(100, max(0, round($value / $max * 100)));
@endphp

<div class="{{ $wrapper }}">
    @if ($label)
        <div class="{{ $header }}">
            <label for="{{ $id }}" class="{{ $labelClass }}">{{ $label }}</label>
            @if ($percent !== null)
                <span class="{{ $valueClass }}">{{ $percent }}%</span>
            @endif
        </div>
    @endif
    <progress {{ $attributes->merge(['id' => $id, 'value' => $value, 'max' => $max])->class([$bar]) }}></progress>
</div>
```

```blade
<x-markas.progress label="Mengunggah berkas" :value="60" />
<x-markas.progress label="Penyimpanan terpakai" :value="3" :max="4" />
<x-markas.progress label="Menyiapkan laporan" />
```

### React

Simpan di `src/components/markas/Progress.tsx`. Tanpa dependensi tambahan.

```tsx
import { useId, type ComponentProps, type ReactNode } from "react";

const wrapper = "grid gap-1.5";
const header = "flex items-center justify-between gap-4 text-sm";
const labelClass = "font-medium text-ink";
const valueClass = "text-muted tabular-nums";
const bar =
  "block h-2 w-full appearance-none overflow-hidden rounded-full border-0 bg-subtle [&::-webkit-progress-bar]:bg-subtle [&::-webkit-progress-value]:rounded-full [&::-webkit-progress-value]:bg-primary [&::-webkit-progress-value]:transition-[width] [&::-webkit-progress-value]:duration-200 [&::-webkit-progress-value]:ease-out [&::-moz-progress-bar]:rounded-full [&::-moz-progress-bar]:bg-primary indeterminate:animate-pulse indeterminate:bg-primary/30 indeterminate:[&::-webkit-progress-bar]:bg-primary/30 motion-reduce:animate-none motion-reduce:[&::-webkit-progress-value]:transition-none";
const cx = (...c: (string | false | null | undefined)[]) =>
  c.filter(Boolean).join(" ");

const percentOf = (value: number, max: number): number =>
  Math.min(100, Math.max(0, Math.round((value / max) * 100)));

export type ProgressProps = Omit<ComponentProps<"progress">, "value"> & {
  value?: number | null;
  max?: number;
  label?: ReactNode;
};

export function Progress({
  value = null,
  max = 100,
  label,
  id,
  className,
  ...props
}: ProgressProps) {
  const generatedId = useId();
  const progressId = id ?? generatedId;

  return (
    <div className={wrapper}>
      {label && (
        <div className={header}>
          <label htmlFor={progressId} className={labelClass}>
            {label}
          </label>
          {value !== null && (
            <span className={valueClass}>{percentOf(value, max)}%</span>
          )}
        </div>
      )}
      <progress
        id={progressId}
        value={value ?? undefined}
        max={max}
        className={cx(bar, className)}
        {...props}
      />
    </div>
  );
}
```

```tsx
import { Progress } from "@/components/markas/Progress";

<Progress label="Mengunggah berkas" value={60} />
<Progress label="Penyimpanan terpakai" value={3} max={4} />
<Progress label="Menyiapkan laporan" />
```

### Vue

Simpan di `src/components/markas/Progress.vue`. Tanpa dependensi tambahan.

```vue
<script setup lang="ts">
import { computed, useId } from "vue";

defineOptions({ inheritAttrs: false });

const props = withDefaults(
  defineProps<{
    value?: number | null;
    max?: number;
    label?: string;
    id?: string;
  }>(),
  { value: null, max: 100, label: undefined, id: undefined },
);

const wrapper = "grid gap-1.5";
const header = "flex items-center justify-between gap-4 text-sm";
const labelClass = "font-medium text-ink";
const valueClass = "text-muted tabular-nums";
const bar =
  "block h-2 w-full appearance-none overflow-hidden rounded-full border-0 bg-subtle [&::-webkit-progress-bar]:bg-subtle [&::-webkit-progress-value]:rounded-full [&::-webkit-progress-value]:bg-primary [&::-webkit-progress-value]:transition-[width] [&::-webkit-progress-value]:duration-200 [&::-webkit-progress-value]:ease-out [&::-moz-progress-bar]:rounded-full [&::-moz-progress-bar]:bg-primary indeterminate:animate-pulse indeterminate:bg-primary/30 indeterminate:[&::-webkit-progress-bar]:bg-primary/30 motion-reduce:animate-none motion-reduce:[&::-webkit-progress-value]:transition-none";

const generatedId = useId();
const progressId = computed(() => props.id ?? generatedId);
const percent = computed(() =>
  props.value === null
    ? null
    : Math.min(100, Math.max(0, Math.round((props.value / props.max) * 100))),
);
</script>

<template>
  <div :class="wrapper">
    <div v-if="props.label" :class="header">
      <label :for="progressId" :class="labelClass">{{ props.label }}</label>
      <span v-if="percent !== null" :class="valueClass">{{ percent }}%</span>
    </div>
    <progress
      :id="progressId"
      :value="props.value ?? undefined"
      :max="props.max"
      :class="bar"
      v-bind="$attrs"
    />
  </div>
</template>
```

```vue
<script setup lang="ts">
import Progress from "@/components/markas/Progress.vue";
</script>

<template>
  <Progress label="Mengunggah berkas" :value="60" />
  <Progress label="Penyimpanan terpakai" :value="3" :max="4" />
  <Progress label="Menyiapkan laporan" />
</template>
```

### Svelte

Simpan di `src/lib/components/markas/Progress.svelte`. Tanpa dependensi tambahan.

```svelte
<script lang="ts">
  import type { HTMLProgressAttributes } from "svelte/elements";

  const wrapper = "grid gap-1.5";
  const header = "flex items-center justify-between gap-4 text-sm";
  const labelClass = "font-medium text-ink";
  const valueClass = "text-muted tabular-nums";
  const bar =
    "block h-2 w-full appearance-none overflow-hidden rounded-full border-0 bg-subtle [&::-webkit-progress-bar]:bg-subtle [&::-webkit-progress-value]:rounded-full [&::-webkit-progress-value]:bg-primary [&::-webkit-progress-value]:transition-[width] [&::-webkit-progress-value]:duration-200 [&::-webkit-progress-value]:ease-out [&::-moz-progress-bar]:rounded-full [&::-moz-progress-bar]:bg-primary indeterminate:animate-pulse indeterminate:bg-primary/30 indeterminate:[&::-webkit-progress-bar]:bg-primary/30 motion-reduce:animate-none motion-reduce:[&::-webkit-progress-value]:transition-none";

  const percentOf = (value: number, max: number): number =>
    Math.min(100, Math.max(0, Math.round((value / max) * 100)));

  type Props = Omit<HTMLProgressAttributes, "value" | "max"> & {
    /** Empty (null) shows an indeterminate bar. */
    value?: number | null;
    max?: number;
    label?: string;
  };

  let {
    value = null,
    max = 100,
    label,
    id,
    class: className,
    ...rest
  }: Props = $props();

  const generatedId = $props.id();
  const progressId = $derived(id ?? generatedId);
</script>

<div class={wrapper}>
  {#if label}
    <div class={header}>
      <label for={progressId} class={labelClass}>{label}</label>
      {#if value !== null}
        <span class={valueClass}>{percentOf(value, max)}%</span>
      {/if}
    </div>
  {/if}
  <progress
    id={progressId}
    value={value ?? undefined}
    {max}
    class={[bar, className]}
    {...rest}
  ></progress>
</div>
```

```svelte
<script lang="ts">
  import Progress from "$lib/components/markas/Progress.svelte";
</script>

<Progress label="Uploading file" value={60} />
<Progress aria-label="Preparing export" />
```

### Astro

Simpan di `src/components/markas/Progress.astro`. Tanpa dependensi tambahan.

```astro
---
import type { HTMLAttributes } from "astro/types";

const wrapper = "grid gap-1.5";
const header = "flex items-center justify-between gap-4 text-sm";
const labelClass = "font-medium text-ink";
const valueClass = "text-muted tabular-nums";
const bar =
  "block h-2 w-full appearance-none overflow-hidden rounded-full border-0 bg-subtle [&::-webkit-progress-bar]:bg-subtle [&::-webkit-progress-value]:rounded-full [&::-webkit-progress-value]:bg-primary [&::-webkit-progress-value]:transition-[width] [&::-webkit-progress-value]:duration-200 [&::-webkit-progress-value]:ease-out [&::-moz-progress-bar]:rounded-full [&::-moz-progress-bar]:bg-primary indeterminate:animate-pulse indeterminate:bg-primary/30 indeterminate:[&::-webkit-progress-bar]:bg-primary/30 motion-reduce:animate-none motion-reduce:[&::-webkit-progress-value]:transition-none";

const percentOf = (value: number, max: number): number =>
  Math.min(100, Math.max(0, Math.round((value / max) * 100)));

type Props = Omit<HTMLAttributes<"progress">, "value" | "max"> & {
  /** Empty (null) shows an indeterminate bar. */
  value?: number | null;
  max?: number;
  label?: string;
};

const {
  value = null,
  max = 100,
  label,
  id,
  class: className,
  ...rest
} = Astro.props;
const progressId = id ?? `markas-progress-${crypto.randomUUID().slice(0, 8)}`;
---

<div class={wrapper}>
  {
    label && (
      <div class={header}>
        <label for={progressId} class={labelClass}>
          {label}
        </label>
        {value !== null && (
          <span class={valueClass}>{percentOf(value, max)}%</span>
        )}
      </div>
    )
  }
  <progress
    id={progressId}
    value={value ?? undefined}
    max={max}
    class:list={[bar, className]}
    {...rest}></progress>
</div>
```

```astro
---
import Progress from "@/components/markas/Progress.astro";
---

<Progress label="Uploading file" value={60} />
<Progress aria-label="Preparing export" />
```

### Angular

Simpan di `src/app/markas/progress.component.ts`. Tanpa dependensi tambahan.

```ts
import {
  ChangeDetectionStrategy,
  Component,
  computed,
  input,
  numberAttribute,
} from "@angular/core";

const wrapper = "grid gap-1.5";
const header = "flex items-center justify-between gap-4 text-sm";
const labelClass = "font-medium text-ink";
const valueClass = "text-muted tabular-nums";
const bar =
  "block h-2 w-full appearance-none overflow-hidden rounded-full border-0 bg-subtle [&::-webkit-progress-bar]:bg-subtle [&::-webkit-progress-value]:rounded-full [&::-webkit-progress-value]:bg-primary [&::-webkit-progress-value]:transition-[width] [&::-webkit-progress-value]:duration-200 [&::-webkit-progress-value]:ease-out [&::-moz-progress-bar]:rounded-full [&::-moz-progress-bar]:bg-primary indeterminate:animate-pulse indeterminate:bg-primary/30 indeterminate:[&::-webkit-progress-bar]:bg-primary/30 motion-reduce:animate-none motion-reduce:[&::-webkit-progress-value]:transition-none";

const percentOf = (value: number, max: number): number =>
  Math.min(100, Math.max(0, Math.round((value / max) * 100)));

/** Empty (null or undefined) stays null, so the bar is indeterminate. */
const optionalNumber = (value: unknown): number | null =>
  value === null || value === undefined ? null : numberAttribute(value);

let nextId = 0;

/**
 * Host stays out of layout (display: contents). id, aria-label, and class move to the
 * progress element, so the host attributes are cleared to avoid duplicate ids and labels.
 */
@Component({
  selector: "markas-progress",
  changeDetection: ChangeDetectionStrategy.OnPush,
  host: {
    class: "contents",
    "[attr.id]": "null",
    "[attr.aria-label]": "null",
  },
  template: `
    <div [class]="wrapper">
      @if (label()) {
        <div [class]="header">
          <label [for]="progressId()" [class]="labelClass">{{ label() }}</label>
          @if (percent() !== null) {
            <span [class]="valueClass">{{ percent() }}%</span>
          }
        </div>
      }
      <progress
        [id]="progressId()"
        [attr.value]="value()"
        [attr.max]="max()"
        [attr.aria-label]="ariaLabel() ?? null"
        [class]="barClasses()"
      ></progress>
    </div>
  `,
})
export class Progress {
  /** Empty (null) shows an indeterminate bar. */
  readonly value = input<number | null, unknown>(null, {
    transform: optionalNumber,
  });
  readonly max = input(100, { transform: numberAttribute });
  readonly label = input<string>();
  readonly id = input<string>();
  readonly ariaLabel = input<string | undefined>(undefined, {
    alias: "aria-label",
  });
  readonly userClass = input("", { alias: "class" });

  protected readonly wrapper = wrapper;
  protected readonly header = header;
  protected readonly labelClass = labelClass;
  protected readonly valueClass = valueClass;
  private readonly generatedId = `markas-progress-${nextId++}`;
  protected readonly progressId = computed(() => this.id() ?? this.generatedId);
  protected readonly percent = computed(() => {
    const value = this.value();
    return value === null ? null : percentOf(value, this.max());
  });
  protected readonly barClasses = computed(() =>
    [bar, this.userClass()].filter(Boolean).join(" "),
  );
}
```

```ts
import { Component } from "@angular/core";
import { Progress } from "./markas/progress.component";

@Component({
  selector: "app-upload",
  imports: [Progress],
  template: `
    <markas-progress label="Uploading file" [value]="60" />
    <markas-progress aria-label="Preparing export" />
  `,
})
export class Upload {}
```

## Props

| Nama | Tipe | Default | Keterangan |
| --- | --- | --- | --- |
| `value` | `number \| null` | null | Nilai saat ini. null membuat progress tak tentu (indeterminate) dengan animasi denyut. |
| `max` | `number` | 100 | Nilai maksimum. |
| `label` | `string` | - | Label di atas bilah, dihubungkan lewat label for. Persentase tampil di kanan bila value terisi. |
| `id` | `string` | auto | Id elemen progress. |

## Aksesibilitas

- Memakai elemen progress native, jadi role progressbar dan nilainya terbaca otomatis.
- Label terhubung lewat label for. Tanpa label, isi aria-label.
- Animasi mode tak tentu dimatikan saat prefers-reduced-motion.

## Catatan

- Tanpa `value`, progress menjadi tak tentu dan berdenyut. Animasi mati saat `prefers-reduced-motion`.
- Tanpa `label`, isi `aria-label` supaya progress punya nama.
- Persentase dibulatkan dan dibatasi 0 sampai 100.
