{"id":23721476,"url":"https://github.com/chrisuser/react-usage-bar","last_synced_at":"2026-04-11T22:11:55.578Z","repository":{"id":38048426,"uuid":"269938133","full_name":"ChrisUser/react-usage-bar","owner":"ChrisUser","description":"React component to display the usage of space or the sectors for which a container is divided.","archived":false,"fork":false,"pushed_at":"2024-12-14T11:50:57.000Z","size":5299,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-12-14T12:29:09.672Z","etag":null,"topics":["bar","component","design","disk-usage","react","react-component","storybook","typescript","usage","usage-data"],"latest_commit_sha":null,"homepage":"https://chrisuser.github.io/react-usage-bar/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ChrisUser.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-06T09:53:50.000Z","updated_at":"2024-12-14T11:50:56.000Z","dependencies_parsed_at":"2024-02-20T21:45:07.636Z","dependency_job_id":"26977f53-4add-458a-bc6c-fd45af57757e","html_url":"https://github.com/ChrisUser/react-usage-bar","commit_stats":{"total_commits":68,"total_committers":4,"mean_commits":17.0,"dds":"0.16176470588235292","last_synced_commit":"e3c0f7b4aa2dda7f74b87e41406370aa463583ad"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisUser%2Freact-usage-bar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisUser%2Freact-usage-bar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisUser%2Freact-usage-bar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisUser%2Freact-usage-bar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ChrisUser","download_url":"https://codeload.github.com/ChrisUser/react-usage-bar/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231919154,"owners_count":18445874,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bar","component","design","disk-usage","react","react-component","storybook","typescript","usage","usage-data"],"created_at":"2024-12-30T22:20:38.963Z","updated_at":"2026-04-11T22:11:55.572Z","avatar_url":"https://github.com/ChrisUser.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# React Usage Bar Graphic Component\n\n![React Usage Bar first example](example.png)\n![React Usage Bar compact design](example_compact.png)\n\n![Latest version](https://img.shields.io/npm/v/react-usage-bar?logo=npm)\n![Build passing](https://img.shields.io/badge/build-passing-darkgreen.svg)\n![Contributions welcome](https://img.shields.io/badge/contributions-welcome-darkorange.svg)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\nDisplay disc sectors, stats and more with this lightweight user-friendly React component.\\\nNow compatible with [Tailwind](https://tailwindcss.com/).\n\n## Installation\n\nInstall via npm\n\n```sh\nnpm install react-usage-bar --save\n```\n\nor yarn\n\n```sh\nyarn add react-usage-bar\n```\n\n\u003cbr\u003e\n\n## Compatibility table\n\n| Package v | Node       | React          |\n| --------- | ---------- | -------------- |\n| \u003c= 1.1.18 | \u003c= 16.14.x | 16.x - 17.x   |\n| \u003e= 1.1.19 | 18.x.x     | 18.x           |\n| \u003e= 1.2.2  | 20.x.x     | 18.x           |\n| \u003e= 1.3.0  | 20.x.x     | 18.x - 19.x   |\n\n\u003cbr\u003e\n\n## Usage\n\nLive **demo** at: [https://chrisuser.github.io/react-usage-bar/](https://chrisuser.github.io/react-usage-bar/)\n\nThe usage bar needs to receive an array of items. In order to display all the values correctly every item should follow this interface:\n\n### Item type\n\n| Attribute    | Type   | Required |                                                                                        |\n| ------------ | ------ | -------- | -------------------------------------------------------------------------------------- |\n| value        | number | Yes      |                                                                                        |\n| name         | string | Yes      |                                                                                        |\n| color        | string | No       | Supports hex, rgb, hsl, named colors, and CSS gradients                                |\n| className    | string | No       | ![tailwind compatible](https://img.shields.io/badge/Tailwind-compatible-darkgreen.svg) |\n| dotClassName | string | No       | ![tailwind compatible](https://img.shields.io/badge/Tailwind-compatible-darkgreen.svg) |\n\nThe `value` attribute indicates the amount of space taken up by the sector with a specific `name`. The `color` property can be utilized to define the background color of that particular portion in the bar. It also supports CSS gradients like `linear-gradient(90deg, #4facfe, #00f2fe)`.\n\nTo further customize the sector element, you can apply your own CSS classes or Tailwind classes using the `className` attribute.\n\nIn case you are using the **compact layout** and have not specified a `color` value, you can customize the `dotClassName` similarly to the `className` attribute.\n\n\u003e The defined `color` property value will have a **priority on the background color** defined in the `className` and/or `dotClassName` ones.\\\n\u003e \u003cbr /\u003e\n\u003e It is recommended to use **exclusively** `color` or one of the two other properties per item.\n\n### Example\n\n```tsx\nimport UsageBar from 'react-usage-bar'\nimport 'react-usage-bar/dist/index.css'\n\nconst App = () =\u003e {\n    const itemsToDisplay = [\n        {\n            name: 'UI',\n            value: 10,\n            color: '#000000'\n        },\n        {\n            name: 'Photos',\n            value: 30\n        },\n        {\n            name: 'Videos',\n            value: 15\n        },\n        {\n            name: 'System Data',\n            value: 33\n        },\n        {\n            name: 'Other',\n            value: 8\n        }\n    ]\n\n    return \u003cUsageBar items={itemsToDisplay} total={100} showFallbackColors /\u003e\n}\n\nexport default App\n```\n\nThe `total` prop is also required.\n\n\u003cbr\u003e\n\n## TypeScript\n\nThe `Item` and `UsageBarProps` types are exported and can be imported for use in your own code:\n\n```tsx\nimport UsageBar, { type Item, type UsageBarProps } from 'react-usage-bar'\n\nconst items: Item[] = [\n    { name: 'Photos', value: 30, color: '#E85D04' },\n    { name: 'Videos', value: 15 }\n]\n```\n\n\u003cbr\u003e\n\n## Props (Options)\n\n### Core\n\n### **items** | _Item[]_ | **required**\n\nThe array of items to display in the bar.\n\n### **total** | _number_ | **required**\n\nThe total value representing 100% of the bar.\n\n### **showPercentage** | _boolean_ | default: `false`\n\nWhen true, shows the percentage value of all the elements.\n\n### **showLabels** | _boolean_ | default: `true`\n\nWhen false, hides all the tooltips or labels of the items.\n\n### **darkMode** | _boolean_ | default: `false`\n\nWhen true, enables the component to work in dark-mode.\n\n### **compactLayout** | _boolean_ | default: `false`\n\nWhen true, enables the compact design with labels below the bar instead of tooltips.\n\n### **showFallbackColors** | _boolean_ | default: `false`\n\nWhen true, dynamically assigns a color from the built-in palette to items without an explicit `color` value.\n\n### **errorMessage** | _string_ | default: `Error: Total elements values exceed 100%.`\n\nCustomize the error string that appears when the total values of the provided items exceeds 100%.\n\n---\n\n### Appearance\n\n### **height** | _number | string_ | default: `8pt`\n\nControls the height of the bar. Numbers are treated as pixels.\n\n### **borderRadius** | _number | string_ | default: `4pt`\n\nControls the border radius of the bar. Numbers are treated as pixels.\n\n### **segmentGap** | _number_\n\nSpacing in pixels between segments. When set, each segment becomes individually rounded.\n\n### **segmentBorderRadius** | _number_\n\nPer-segment border radius in pixels. Overrides the default segment rounding.\n\n### **animated** | _boolean_ | default: `false`\n\nWhen true, segments smoothly animate their width changes via CSS transitions.\n\n### **transitionDuration** | _number_ | default: `0.4`\n\nDuration of the segment width animation in seconds. Only applies when `animated` is true.\n\n### **rtl** | _boolean_ | default: `false`\n\nWhen true, renders the bar in right-to-left direction.\n\n---\n\n### Interaction\n\n### **showTooltipOnHover** | _boolean_ | default: `false`\n\nWhen true, tooltips are hidden by default and only appear when hovering over a segment. Hovered segments are highlighted.\n\n### **onItemClick** | _(item: Item, index: number) =\u003e void_\n\nCallback fired when a bar segment is clicked. Does not apply to the remaining segment.\n\n---\n\n### Custom Rendering\n\n### **renderTooltip** | _(item: Item, percentage: string) =\u003e ReactNode_\n\nCustom render function for tooltip or label content. Receives the item and its percentage string.\n\n### **renderSegment** | _(item: Item, percentage: string, defaultStyle: CSSProperties) =\u003e ReactNode_\n\nCustom render function for the entire bar segment. Receives the item, percentage string, and a style object containing `width`, `backgroundColor`, animation, and border-radius values. Apply `defaultStyle` to your element for correct sizing.\n\n### **remaining** | _{ name: string; color?: string }_\n\nWhen provided, an additional segment is added to the bar representing the unused space (`total - sum of items`). Useful for storage-style UIs.\n\n```tsx\n\u003cUsageBar items={items} total={100} remaining={{ name: 'Available', color: '#e0e0e0' }} /\u003e\n```\n\n---\n\n### Accessibility\n\n### **ariaLabel** | _string_ | default: `Usage bar`\n\nSets the `aria-label` on the root container. Each segment automatically gets `role=\"meter\"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, and `aria-label` attributes.\n\n---\n\n\u003cbr\u003e\n\n**Custom classes props:** add custom or Tailwind classes to elements of the component.\n\n### **className** | _string_\n\nStandard React `className` applied to the root container div.\n\n### **usageBarContainerClassName** | _string_\n\nCan customize the main div of the component.\n\n### **usageBarClassName** | _string_\n\nCan customize the actual bar element of the component.\n\n### **tooltipClassName** | _string_\n\nCan customize the tooltip div of the item in which are written all the textual info.\n\n### **errorMessageClassName** | _string_\n\nCan customize the style of the error message.\n\n\u003cbr\u003e\n\n## CSS Styles\n\nYou must import the style directly from the package directory, like this:\n\n```javascript\nimport 'react-usage-bar/dist/index.css'\n```\n\nThe project variables are:\n\n-   `--text-color`\n-   `--background-tooltip-color`\n-   `--background-bar-color`\n\nThe main css classes are the following:\n\n### `.u-UsageBar__error`\n\nThe error message.\n\n### `.u-UsageBar-light`\n\nThe class that contains all the colors for the light mode.\n\n### `.u-UsageBar-dark`\n\nThe class that contains all the colors for the dark mode.\n\n### `.c-UsageBar`\n\nThe main div of the component.\n\n### `.o-UsageBar__bar`\n\nThe actual bar of the component.\n\n### `.o-UsageBar__bar__element`\n\nThe single item represented in the bar. This class is vastly used.\n\n### `.o-UsageBar__bar__tooltip`\n\nThe tooltip of the item in which are written all the textual info.\n\n-   `.o-UsageBar__bar__tooltip__percentage` - Used to control the style of the percentage labels.\n-   `::after` - Is used to make the triangular shape on the bottom (or top) of the tooltips.\n\n### `.o-UsageBar__bar--hover-tooltips`\n\nApplied to the bar when `showTooltipOnHover` is enabled. Hides tooltips by default and shows them on segment hover.\n\n### `.o-UsageBar__bar__elements__labels__container`\n\nUsed in the compact layout to list all the labels for the elements.\n\n### `.o-UsageBar__bar__elements__label`\n\nThe labels for the elements of the bar.\n\n### `.o-UsageBar__bar__elements__label--dot`\n\nThe colored dot before the label of the elements.\n\n\u003cbr\u003e\n\n## Docs\n\nYou can run the project in a local environment using [Storybook](https://storybook.js.org/):\n\n```\n$ yarn storybook\n```\n\n\u003cbr\u003e\n\n## Contribution\n\nIf you have a suggestion that would make this component better feel free to fork the project and open a pull request or create an issue for any idea or bug you find.\\\nRemember to follow the [Contributing Guidelines](https://github.com/ChrisUser/.github/blob/main/CONTRIBUTING.md).\n\n\u003cbr\u003e\n\n## Licence\n\nReact Usage Bar is [MIT licensed](https://github.com/ChrisUser/react-usage-bar/blob/master/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrisuser%2Freact-usage-bar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchrisuser%2Freact-usage-bar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrisuser%2Freact-usage-bar/lists"}