{"id":13611037,"url":"https://github.com/jh3y/ep","last_synced_at":"2025-04-04T15:05:18.869Z","repository":{"id":13892962,"uuid":"16591292","full_name":"jh3y/ep","owner":"jh3y","description":"enhance your HTML5 progress bars with minimal effort!","archived":false,"fork":false,"pushed_at":"2017-10-22T18:57:50.000Z","size":1485,"stargazers_count":646,"open_issues_count":1,"forks_count":48,"subscribers_count":20,"default_branch":"master","last_synced_at":"2024-10-30T05:57:34.162Z","etag":null,"topics":["css-helper","html5","html5-elements","html5-progress","js-helpers","progress-bar","progressbar"],"latest_commit_sha":null,"homepage":"http://jh3y.github.io/ep","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jh3y.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}},"created_at":"2014-02-06T19:43:54.000Z","updated_at":"2024-10-22T08:35:43.000Z","dependencies_parsed_at":"2022-08-24T04:41:06.829Z","dependency_job_id":null,"html_url":"https://github.com/jh3y/ep","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jh3y%2Fep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jh3y%2Fep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jh3y%2Fep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jh3y%2Fep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jh3y","download_url":"https://codeload.github.com/jh3y/ep/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247198446,"owners_count":20900079,"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":["css-helper","html5","html5-elements","html5-progress","js-helpers","progress-bar","progressbar"],"created_at":"2024-08-01T19:01:51.129Z","updated_at":"2025-04-04T15:05:18.852Z","avatar_url":"https://github.com/jh3y.png","language":"JavaScript","readme":"[![Build Status](https://travis-ci.org/jh3y/ep.svg?branch=master)](https://travis-ci.org/jh3y/ep)\n\n![alt tag](https://github.com/jh3y/pics/blob/master/ep/ep.png)\n## enhance your HTML5 `\u003cprogress\u003e` bars with minimal effort!\n\n![alt tag](https://github.com/jh3y/pics/blob/master/ep/ep.gif)\n\nThe `\u003cprogress\u003e` element doesn't always play nice.\n\nIt doesn't have a consistent appearance across the popular browsers. In addition, different browsers impose different limitations on the `\u003cprogress\u003e` element.\n\nBecause of this, it's often overlooked in favor of styled `\u003cdiv\u003e` combos.\n\n`ep` tackles this;\n\n* Cross browser reset and styling to pull `\u003cprogress\u003e` element in line with modern slim-style bars\n* CSS helpers that provide classes and attributes to deal with things like positioning, growth style, simulation etc.\n* Optional JS helper for better control and interaction with `\u003cprogress\u003e` elements. For example; being able to hook into network request status and display this to the end user.\n* Plays nice wherever the `\u003cprogress\u003e` element is supported!\n\n```js\n  const myEp = new Ep(document.querySelector('progress'));\n  const makeRequest = () =\u003e {\n    myEp.simulate();\n    const xhttp = new XMLHttpRequest();\n    xhttp.onreadystatechange = function() {\n      if (this.readyState == 4 \u0026\u0026 this.status == 200) {\n        myEp.complete();\n      }\n    };\n    xhttp.open('GET', '/index.html', true);\n    xhttp.send();\n  };\n  (myEp._VALUE) ? myEp.set(0, makeRequest) : makeRequest();\n```\n\n## Index\n\n* [Browser support](https://github.com/jh3y/ep#browser-support)\n  * [Caveats](https://github.com/jh3y/ep#caveats)\n* [Usage](https://github.com/jh3y/ep#usage)\n  * [Install](https://github.com/jh3y/ep#install)\n  * [Just using the stylesheet](https://github.com/jh3y/ep#just-using-the-stylesheet)\n  * [Including the optional JS helper](https://github.com/jh3y/ep#including-the-optional-js-helper)\n  * [Integrating with your own SASS files](https://github.com/jh3y/ep#integrating-with-your-own-sass-files)\n  * [CSS Helpers Api](https://github.com/jh3y/ep#css-helpers-api)\n    * [Aesthetic helpers](https://github.com/jh3y/ep#aesthetic-helpers)\n    * [Behavioural helpers](https://github.com/jh3y/ep#behavioural-helpers)\n    * [Sass variables](https://github.com/jh3y/ep#sass-variables)\n    * [Sass mixin](https://github.com/jh3y/ep#sass-mixin)\n  * [Javascript Helper Api](https://github.com/jh3y/ep#javascript-helper-api)\n    * [Hooking into network requests](https://github.com/jh3y/ep#hooking-into-network-requests)\n* [What happened to progrecss?](https://github.com/jh3y/ep#what-happened-to-progrecss)\n* [Development](https://github.com/jh3y/ep#development)\n* [Contributing](https://github.com/jh3y/ep#contributing)\n* [License](https://github.com/jh3y/ep#license)\n\n\n## Browser support\n\n| Chrome  | Firefox | Safari | Opera | Edge | IE(_10+_)|\n| ------------- |-------------| -----| -----|-----|-----|\n| :smile:   | :smile:  | :smile:  | :smile: | :smile: | :smile: |\n\n### Caveats\n* iOS Safari doesn't like indeterminate `\u003cprogress\u003e` elements. Get round this by not setting your `\u003cprogress\u003e` element to be indeterminate but instead using the helper class `ep--indeterminate` which will mock the indeterminate state.\n* In IE, ensure that the `max` attribute is set when using specific values. If no `max` is set, the value won't go higher than `1` :cry:\n\n## Usage\nYou have various options with how to use `ep`;\n\n* Use the stylesheet by adding [`ep.css`](https://github.com/jh3y/ep/blob/master/dist/ep.css) to your app.\n* Include the optional JS helper [`ep.js`](https://github.com/jh3y/ep/blob/master/ep.js) for some more control.\n* Integrate the `ep` styles with your own SASS by importing the parts you need.\n\n### Install\nYou can grab a copy of `ep` through `bower` or `npm`;\n\n```shell\n  bower install ep\n\n  npm install @jh3y/ep\n```\n\n### Just using the stylesheet\nIf you're just using the stylesheet, you just need to include it. No alterations need to be made to your current `\u003cprogress\u003e` elements unless you want to make use of some of the helper classes and attributes.\n\n```html\n  \u003cprogress value=\"75\" max=\"100\"\u003e\u003c/progress\u003e\n\n  \u003cprogress class=\"ep--fixed ep--top\" value=\"75\" max=\"100\"\u003e\u003c/progress\u003e\n\n  \u003cprogress data-simulate=\"true\" value=\"75\" max=\"100\"\u003e\u003c/progress\u003e\n```\n\nNeed to change the color of a `\u003cprogress\u003e` element or something else? Override the rule. For example, change the color to `purple`;\n```css\n  progress {\n    background: purple;\n  }\n\n  progress::-moz-progress-bar {\n    background: purple;\n  }\n\n  progress::-webkit-progress-bar {\n    background: purple;\n  }\n\n  progress::-webkit-progress-value {\n    background: purple;\n  }\n```\nThere is also a `SASS` mixin included to as a shorthand to do this;\n```sass\n@import '~ep/mixins';\n.progress {\n  @include color-bar(purple);\n}\n```\n### Including the optional JS helper\nIf you choose to use the optional JS helper. You'll have access to the `Ep` constructor class. Refer to the JS API for further info.\n\n```js\n  const el   = document.querySleect\n  const myEp = new Ep()\n```\n\n### Integrating with your own SASS files\nSay you want to pick and choose pieces of `ep`. Simple. This is actually the easiest way to override `ep`s configuration variables. `ep` makes use of the `!default` flag in `sass` to make this possible. For example; let's say we only want the core styles but we don't want any opacity and we want the primary color to be be purple.\n\n```sass\n  $ep-fg: purple;\n  $ep-opacity: 1;\n  @import '~ep/core'\n```\n\n### CSS Helpers API\nWithout the use of JS, `ep` provides some CSS helpers in the form of attributes and classes you can apply to `\u003cprogress\u003e` elements to define behaviors.\n\n#### Aesthetic helpers\nAesthetic helpers come in the form of classes;\n\n* `ep--top` - position absolute top\n* `ep--bottom` - position absolute bottom\n* `ep--fixed` - position fixed\n* `ep--spread` - change style of `\u003cprogress\u003e` bar to spread\n* `ep--indeterminate` - show indeterminate state\n\n#### Behavioural helpers\nBehavioural helpers come in the form of attributes that must be applied to your `\u003cprogress\u003e` elements;\n\n* `data-complete` - complete progress(_set to 100 and hide, more control with JS helper_)\n* `data-simulate` - slowly simulate progress in steps up to `99%`over 30 seconds(_request timeout_), can be configured/overrode\n* `data-mock=\"value\"` - mock progress for given number of seconds\n* `data-staggered-mock=\"value\"` - mock progress but with staggered style\n* `data-timer=\"value\"` - use progress element as timer for given seconds\n* `data-pause` - pauses any animation in place such as timer, mock etc.\n\n_NOTE::_ The `mock`, `staggered-mock`, `timer` and `simulate` behaviors have duration defaults set in the source. For example; the max duration is set at `4`. This is to keep the size down. But these can easily be altered by building your own version of `ep` or adding rules for the durations you require. For example; I want the simulation to only take `10s` and a timer that will take `15s`.\n\n```css\nprogress[data-simulate] {\n  animation-duration: 10s;\n  animation-timing-function: steps(28);\n}\n\nprogress[data-timer=\"15\"] {\n  animation-duration: 15s;\n}\n\n```\n\n#### Sass variables\n`ep` leverages the `!default` flag in Sass so it's easier to override `ep` configuration variables. Simply set any of the following variables before importing `ep`.\n\n* `$ep-ns: ep` - set the class helper prefix\n* `$ep-height: 6px` - set the height of `\u003cprogress\u003e` elements\n* `$ep-fg: #3498db` - set the primary color of `\u003cprogress\u003e` elements\n* `$ep-indeterminate-fg: $ep-fg` - set the primary color when in indeterminate state\n* `$ep-opacity: .6` - set the opacity of `\u003cprogress\u003e` elements\n* `$ep-transition: .25s` - set the duration for `\u003cprogress\u003e` elements to transition value\n* `$ep-timeout-threshold: 30` - the time it takes for simulation to complete in seconds\n* `$ep-simulate-max: 99` - at which value should simulation stop\n* `$ep-mocks-min: 1` - minimum mocking duration in seconds\n* `$ep-mocks-max: 4` - maximum mocking duration in seconds\n* `$ep-staggered-mocks-min: 1` - minimum staggered mock duration in seconds\n* `$ep-staggered-mocks-max: 4` - maximum staggered mock duration in seconds\n* `$ep-timers-min: 1` - minimum timer duration in seconds\n* `$ep-timers-max: 4` - maximum timer duration in seconds\n\n```sass\n$ep-fg: #e74c3c3;\n$ep-opacity: .8;\n// import with default variables override\n@import '~ep/core';\n```\n\n#### Sass mixin\n`ep` also has a mixin available for coloring `progress` elements. Simply pass a color to `color-bar`. You may use this without even importing the `ep` reset if you just want to color some `progress` elements.\n\n```sass\n@import '~ep/mixins';\n\n.my-progress-element { @include color-bar(#7bff7b); }\n\n```\n\n### Javascript helper/API\n`ep` also provides an optional Javascript helper/api. This can be used for convenience and also gives a little more control and power when interacting with `\u003cprogress\u003e` elements. It doesn't create any extra elements, but you must pass a `HTMLProgressElement` into the constructor.\n\n```js\nconst bar = document.querySelector('progress');\nconst myEp = new Ep(bar);\n```\nIt's main purpose is that it saves you the burden of having to set/remove attributes/classes. But it also provides some nice to haves such as being able to hook into when progress is complete or set.\n\nThe source is quite heavily documented and written with `babel` so be sure to check that out [here](https://github.com/jh3y/ep/blob/master/src/script/entries/ep/index.js).\n\nAs for the methods available(`?` denotes an optional parameter);\n\n* `set({number} val, ? {function} cb)` - Sets `\u003cprogress\u003e` value with optional callback.\n* `setSpread(? {bool} spread)` - Set whether `\u003cprogress\u003e` element should be spred style. By default will set to false.\n* `setIndeterminate(? {bool} indeterminate)` - Set whether `\u003cprogress\u003e` element is using `indeterminate` helper class. By default, will remove helper class.\n* `togglePause` - Toggles pause attribute for play/pause animation.\n* `setPosition(? {Array string} positions)` - Takes an optional array of positions that will be applied to the element. For example, `['top', 'fixed']` will set `ep--top ep--fixed` class to the `\u003cprogress\u003e` element. If no positions are declared, all currently applied will be wiped.\n* `increase(? {number} value, ? {function} cb)` - Increase progress value by optional increment with an optional callback. By default, increment is 5.\n* `decrease(? {number} value, ? {function} cb)` - Decrease progress value by optional decrement with an optional callback. By default, decrement is 5.\n* `reset` - Resets `\u003cprogress\u003e` value to 0.\n* `mock(? {number} duration, ? {bool} staggered, ? {function} cb)` - Mocks progress with a mocking animation. Optional duration in seconds. Optional staggered attribute defines which mock style use. Optional callback can be invoked when mock is complete. By default, duration is 4.\n* `time(? {number} duration, ? {function} cb)` - Timing mock for using element as timer. Optional duration in seconds. Optional callback can be invoked when timer is complete. By default, duration is 4.\n* `simulate(? {number} step, ? {number} increment, ? {number} max)` - Simulation on the Javascript side is an example where we have more control than we do with CSS. Set a simulation by declaring a step duration in `ms`, an `increment` and a `max` value for the simulation to reach. The default simulation will increment by 5 every second until the `\u003cprogress\u003e` element has a value of 99.\n* `complete(? {function} cb)` - Complete a progress bar by setting value to 100 and then resetting it. Provide optional callback for when complete.\n\n#### Hooking into network requests\nYep. You can easily integrate `ep` to communicate network request status to the end user. The most basic example being something like the following;\n```js\n  const myEp = new Ep(document.querySelector('progress'));\n  const makeRequest = () =\u003e {\n    myEp.simulate();\n    const xhttp = new XMLHttpRequest();\n    xhttp.onreadystatechange = function() {\n      if (this.readyState == 4 \u0026\u0026 this.status == 200) {\n        myEp.complete();\n      }\n    };\n    xhttp.open('GET', '/index.html', true);\n    xhttp.send();\n  }\n  (myEp._VALUE) ? myEp.set(0, makeRequest) : makeRequest();\n```\nWe start with a simple `progress` element. Reset it to make sure it starts at `0` and start a simulation. When we get the `OK` from our network request, set our element to complete :tada:\n\n## What happened to progrecss?\nFor some time, I'd intended to revisit `progre(c)ss` with some ideas I had. When I finally got round to it, I went back over the issues and something struck me. Someone had pointed out why not use the `\u003cprogress\u003e` element?\n\nI'd previously struck this off because I liked being able to add `:pseudo` element progress bars to any element with relative ease where the `:pseudo` elements were available.\n\nHowever, using `:pseudo` elements to display progress isn't ideal and not very semantic.\n\nIt makes more sense to create something that can be integrated without big changes.\n\n`progre(c)ss` is still available under the release tab if you really want it but realistically the code for `progre(c)ss` is as simple as;\n\n```sass\n.progrecss {\n  \u0026:before {\n    color: green;\n    content: '';\n    height: 6px;\n    left: 0;\n    opacity: .8;\n    position: absolute;\n    top: 0;\n  }\n  @for $percent from 1 through 100 {\n    \u0026[data-progrecss-value='#{$percent}'] {\n      \u0026:before {\n        width: $percent * 1%;\n      }\n    }\n  }\n}\n```\n\n## Development\n`ep` is developed using `webpack`, `webpack-dev-server`, `babel` and `sass`.\n\nIt uses a self-documented `Makefile` for development.\n\n### See available tasks\n```shell\n  make\n```\n\n### Setup\n```shell\n  make setup\n```\n\n### Start developing\n```shell\n  make develop\n```\n\n\n## Contributing\nDon't hesitate to post and issue, PR or suggestion. Alternatively, get in touch via email or by tweeting me [@_jh3y](https://twitter.com/_jh3y)! :smile:\n\n## License\nMIT\n\n-----------------\n\nMade real by [@jh3y](https://twitter.com/_jh3y) 2017 :sunglasses:\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjh3y%2Fep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjh3y%2Fep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjh3y%2Fep/lists"}