react-circular-tracker v1.0.3

React Circular Tracker

A customizable and reusable circular progress tracker component for React.JS.

Installation

You can install the package via npm:

npm install react-circular-tracker

Or via yarn:

yarn add react-circular-tracker

Usage

Here's a basic example of how to use the CircularTracker component in your React application:

import React from 'react';
import { CircularTracker } from 'react-circular-tracker';

const App = () => (
  <div>
    <CircularTracker progress={50} />
  </div>
);

export default App;

Props

The CircularTracker component accepts the following props:

Example

Here's a more detailed example demonstrating various props:

Default Example

<CircularTracker
  progress={93}
  isPercentage={true}
  ballStrokeWidth={14}
  fontSize="36"
  fontWeight={"bold"}
  className="default-tracker"
  gradient={[
    { stop: 0, color: "#059669" }, // Emerald-600
    { stop: 1, color: "#047857" }, // Emerald-700
  ]}
  centerBackground="rgba(16, 185, 129, 0.1)"
  textColor="#059669"
/>

Anti-clockwise

<CircularTracker
  progress={-60}
  total={100}
  isPercentage={true}
  strokeWidth={4}
  ballStrokeWidth={12}
  transitionDuration={0.5}
  transitionTimingFunction="ease"
  background="rgba(255, 87, 51, 0.2)"
  hideBall={false}
  hideValue={false}
  gradient={[
    { stop: 0, color: "#E11D48" }, // Rose-600
    { stop: 1, color: "#BE123C" }, // Rose-700
  ]}
  subtitle=""
  className="inverted-tracker"
  suffix="pts"
  centerBackground="transparent"
  fontWeight="bold"
  fontSize="24px"
  inverted={true}
  textColor="#FF5733"
/>

Loading Example

<CircularTracker
  progress={60}
  total={100}
  isPercentage={true}
  strokeWidth={4}
  ballStrokeWidth={12}
  transitionDuration={0.5}
  transitionTimingFunction="ease"
  background="#eef2f5"
  hideBall={false}
  hideValue={false}
  gradient={[
    { stop: 0, color: "#FBBF24" }, // Amber-400
    { stop: 1, color: "#F59E0B" }, // Amber-500
  ]}
  subtitle="Loading..."
  className="loading-tracker"
  suffix="%"
  centerBackground="transparent"
  fontWeight="bold"
  fontSize="24px"
  textColor="#FFC300"
/>

Steps Example

<CircularTracker
  progress={3}
  total={5}
  isPercentage={false}
  strokeWidth={4}
  ballStrokeWidth={12}
  transitionDuration={0.5}
  transitionTimingFunction="ease"
  background="#eef2f5"
  hideBall={false}
  hideValue={false}
  gradient={[
    { stop: 0, color: "#7C3AED" }, // Violet-600
    { stop: 1, color: "#6D28D9" }, // Violet-700
  ]}
  subtitle="STEPS"
  style={{}}
  className="steps-tracker"
  suffix=""
  centerBackground="transparent"
  fontWeight="bold"
  fontSize="24px"
  textColor="#8E44AD"
/>

Icon Example - NEW

You can also use custom icons or any other icon library:

import { ArrowUp } from 'lucide-react';

const App = () => (
  <CircularTracker
    progress={93}
    isPercentage={true}
    hideBall
    strokeWidth={8}
    fontSize="36"
    fontWeight={"bold"}
    className="default-tracker"
    gradient={[
      { stop: 0, color: "#059669" }, // Emerald-600
      { stop: 1, color: "#047857" }, // Emerald-700
    ]}
    roundedBorders
    icon={<ArrowUp size={80} />}
  />
);

Storybook

You can view and interact with the CircularTracker component in Storybook. To start Storybook, run the following command:

npm run storybook

This will start Storybook and open it in your default web browser. You can see different examples of the CircularTracker component and interact with its props.

Contributing

Contributions are welcome! Please follow these steps to contribute:

Opening an Issue

1. Go to the Issues page.
2. Click on the "New Issue" button.
3. Provide a clear and descriptive title for the issue.
4. Describe the issue in detail, including steps to reproduce, expected behavior, and any relevant screenshots or code snippets.

Submitting a Pull Request

1. Fork the repository by clicking the "Fork" button on the repository page.
2. Clone your forked repository to your local machine:

   git clone https://github.com/your-username/react_circular_tracker.git

3. Create a new branch for your feature or bugfix:

   git checkout -b feature-or-bugfix-name

4. Make your changes and commit them with a clear and descriptive commit message:

   git commit -m "Description of the changes"

5. Push your changes to your forked repository:

   git push origin feature-or-bugfix-name

6. Open a pull request from your forked repository to the main repository. Provide a clear and descriptive title and description for your pull request.

Running the Project Locally

1. Clone the repository to your local machine:

   git clone https://github.com/BinaryLeo/react_circular_tracker.git

2. Navigate to the project directory:

   cd react_circular_tracker

3. Install the dependencies:

   npm install

4. Start the Storybook development server:

   npm start

License

This project is licensed under the MIT License. See the LICENSE file for more details.

Author

Leonardo Moura - binaryleo - 2024 Find me on LinkedIn

Acknowledgements

Thanks to all the contributors and the open-source community for their support.