{"slug":"linear-progress","title":"Linear Progress","description":"Using the linear progress machine in your project.","contentType":"component","framework":"react","content":"Linear progress is a simple progress bar that can be used to show the progress\nof a task such as downloading a file, uploading an image, etc.\n\n## Resources\n\n\n[Latest version: v1.35.3](https://www.npmjs.com/package/@zag-js/progress)\n[Logic Visualizer](https://zag-visualizer.vercel.app/progress)\n[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/progress)\n\n\n\n**Features**\n\n- Supports minimum and maximum values\n- Supports indeterminate progress bars\n\n## Installation\n\nInstall the progress package:\n\n```bash\nnpm install @zag-js/progress @zag-js/react\n# or\nyarn add @zag-js/progress @zag-js/react\n```\n\n## Anatomy\n\nCheck the progress anatomy and part names.\n\n> Each part includes a `data-part` attribute to help identify them in the DOM.\n\n\n\n## Usage\n\nImport the progress package:\n\n```jsx\nimport * as progress from \"@zag-js/progress\"\n```\n\nThe progress package exports two key functions:\n\n- `machine` - State machine logic.\n- `connect` - Maps machine state to JSX props and event handlers.\n\n> Pass a unique `id` to `useMachine` so generated element ids stay predictable.\n\nThen use the framework integration helpers:\n\n```jsx\nimport * as progress from \"@zag-js/progress\"\nimport { normalizeProps, useMachine } from \"@zag-js/react\"\nimport { useId } from \"react\"\n\nfunction Progress() {\n  const service = useMachine(progress.machine, { id: useId() })\n\n  const api = progress.connect(service, normalizeProps)\n\n  return (\n    <div {...api.getRootProps()}>\n      <div {...api.getLabelProps()}>Upload progress</div>\n      <div {...api.getTrackProps()}>\n        <div {...api.getRangeProps()} />\n      </div>\n    </div>\n  )\n}\n```\n\n### Setting the value\n\nUse `defaultValue` for uncontrolled state, or `value` for controlled state.\n\n```jsx {2}\nconst service = useMachine(progress.machine, {\n  value: 50,\n})\n```\n\nSubsequently, you can use the `api.setValue` method to set the value of the\nprogress bar.\n\n```jsx\napi.setValue(50)\n```\n\n### Listening for value changes\n\nUse `onValueChange` to react to progress updates.\n\n```jsx\nconst service = useMachine(progress.machine, {\n  onValueChange(details) {\n    // details => { value: number | null }\n    console.log(details.value)\n  },\n})\n```\n\n### Setting the minimum and maximum values\n\nBy default, the progress bar has a minimum value of `0` and a maximum value of\n`100`. You can change these values by passing the `min` and `max` options to the\nmachine.\n\n```jsx {2-3}\nconst service = useMachine(progress.machine, {\n  min: 0,\n  max: 1000,\n})\n```\n\n### Vertical orientation\n\nSet `orientation` to `vertical` for a vertical progress bar.\n\n```jsx\nconst service = useMachine(progress.machine, {\n  orientation: \"vertical\",\n})\n```\n\n### Using the indeterminate state\n\nThe progress component is determinate by default, with the value and max set to\n`50` and `100` respectively.\n\nSet `value` to `null` to indicate an indeterminate value for operations whose\nprogress can't be determined (e.g., attempting to reconnect to a server).\n\n```jsx {2}\nconst service = useMachine(progress.machine, {\n  value: null,\n})\n```\n\n### Customizing value text\n\nProgress bars can only be interpreted by sighted users. To include a text\ndescription to support assistive technologies like screen readers, use the\n`valueText` part.\n\n```jsx\nconst service = useMachine(progress.machine, {\n  translations: {\n    value: ({ value, max }) =>\n      value == null ? \"Loading...\" : `${value} of ${max} items loaded`,\n  },\n})\n```\n\nThen you need to render the `valueText` part in your component.\n\n```jsx\n<div {...api.getValueTextProps()}>{api.valueAsString}</div>\n```\n\n### Localizing percentage formatting\n\nUse `locale` and `formatOptions` to customize number formatting.\n\n```jsx\nconst service = useMachine(progress.machine, {\n  locale: \"fr-FR\",\n  formatOptions: { style: \"percent\", maximumFractionDigits: 1 },\n})\n```\n\n## Styling guide\n\nEach part includes a `data-part` attribute you can target in CSS.\n\n```css\n[data-scope=\"progress\"][data-part=\"root\"] {\n  /* Styles for the root part */\n}\n\n[data-scope=\"progress\"][data-part=\"track\"] {\n  /* Styles for the track part */\n}\n\n[data-scope=\"progress\"][data-part=\"range\"] {\n  /* Styles for the range part */\n}\n```\n\n### Indeterminate state\n\nTo style the indeterminate state, you can use the `[data-state=indeterminate]`\nselector.\n\n```css\n[data-scope=\"progress\"][data-part=\"root\"][data-state=\"indeterminate\"] {\n  /* Styles for the root indeterminate state */\n}\n\n[data-scope=\"progress\"][data-part=\"track\"][data-state=\"indeterminate\"] {\n  /* Styles for the root indeterminate state */\n}\n\n[data-scope=\"progress\"][data-part=\"range\"][data-state=\"indeterminate\"] {\n  /* Styles for the root indeterminate state */\n}\n```\n\n## Methods and Properties\n\n### Machine Context\n\nThe progress machine exposes the following context properties:\n\n<ContextTable name=\"progress\" />\n\n### Machine API\n\nThe progress `api` exposes the following methods:\n\n<ApiTable name=\"progress\" />\n\n### Data Attributes\n\n<DataAttrTable name=\"progress\" />\n\n### CSS Variables\n\n<CssVarTable name=\"progress\" />","package":"@zag-js/progress","editUrl":"https://github.com/chakra-ui/zag/edit/main/website/data/components/linear-progress.mdx"}