Fluid Meter

Dependency free library to represent progress as the amount of fluid in a container.

Demo

https://aarcoraci.github.io/fluid-meter/

Installation

npm i fluid-meter

Usage

The library is higlhly customizable but it can be easily initialized. It requires a DOM container with a setted width and height (inline or css).

<div id="target" style="width:500px;height:500px"></div>

import { CircularFluidMeter } from 'fluid-meter';

const target = document.querySelector('#target');
new CircularFluidMeter(target, {
  initialProgress: 33
});

Bundled version

A new bundled version has been added. It can be accessed via the IIFE on the global scope.

1 - Add the bundle file to your project (can be found as bundle.js in the /dist directory):

<!-- make sure the path is correct -->
<script src="dist/bundle.js"></script>

2 - Access via the IIFE on the global scope (named cfmModule):

const target = document.querySelector("#target");
new cfmModule.CircularFluidMeter(target, {
  initialProgress: 33,
});

Responsiveness

The library is prepared to work on a responsive scenario if needed via the BreakpointValueConfig:

const config = {
  initialProgress: 75,
  borderWidth: [
    {
      resolution: 0,
      value: 15
    },
    {
      resolution: 1024,
      value: 60
    }
  ],
  fontSize: [
    {
      resolution: 0,
      value: 25
    },
    {
      resolution: 768,
      value: 50
    }
  ]
};

See the supported responsive values on the Configuration table

Configuration

Here are some examples on how to use it. It's with typescript but should be the same with plain javascript. https://github.com/aarcoraci/fluid-meter/blob/main/src/main.ts

| option | type | default | info | | ------------------ | ------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | | initialProgress | number | 0 | initial progress to show | | maxProgress | number | 100 | max progress of the meter | | borderWidth | number or BreakpointValueConfig | 30 | border width. Can be a number or an array of breakpoint value configs | | borderColor | string | #75758b | color of the outer border. | | padding | number | 30 | space between the boundaries of the container and the meter. Usefull if drop shadow is enabled | | backgroundColor | string | #9f9fae | meter background color | | showProgress | boolean | true | displays or not the center text | | showBubbles | boolean | true | displays or not the bubbles | | bubbleColor | string | #ffffff | color of the bubbles | | textColor | string | #ffffff | text color | | textDropShadow | boolean | true | text has a small shadow. Helps when colors are too similar or on difficult contrasting scenarios | | textShadowOpacity | number | 1 | intensity of the shadow between 0 and 1: 0 invisible and 1 fully visible | | textShadowColor | string | #000000 | text shadow color | | fontFamily | string | Arial | name of the typeface to use | | fontSize | number or BreakpointValueConfig | 30 | tex size. Can be a number of an array of breakpoint value configs | | use3D | boolean | true | enables details that gives the impresion of depth | | dropShadow | boolean | true | meter drops shadow. Requires some padding to show correctly | | dropShadowColor | string | #000000 | meter shadow color | | progressFormatter | (value: number) => string | (value: number) => Math.round(value).toString() | a function that transforms the value shown in the center of the meter | | fluidConfiguration | FluidLayerConfiguration | {color: '#ff0000',waveSpeed: Speed.NORMAL,horizontalSpeed: Speed.NORMAL} | values of the fluid being displayed |

API and Methods

Example:

import { CircularFluidMeter } from 'fluid-meter';

const target = document.querySelector('#target');
const m = new CircularFluidMeter(target, {
  initialProgress: 50
});

m.targetProgress = 50;
m.dropShadow = false;
m.use3D = false;

List of setters and getters

| setter / getter | info | | ------------------------------- | ----------------------------------- | | progress | number | | maxProgress (only getter) | number | | borderWidth | number or BreakpointValueConfig[] | | borderColor | string | | meterPadding | number | | backgroundColor | string | | textColor | string | | fontFamily | string | | fontSize | number or BreakpointValueConfig[] | | textDropShadow | boolean | | textShadowOpacity | number (between 0 and 1) | | textShadowColor | string | | showProgress | boolean | | showBubbles | boolean | | bubbleColor | string | | use3D | boolean | | dropShadow | boolean | | dropShadowColor | string | | progressFormatter (only getter) | (value: number) => string |

Performance

If yo are using the library on a context where you will be adding it or removing it dynamically you should call dispose when removing it to correctly clear the animation:

meter.dispose();