ACE: Progress Bar

Design

We use Progress Bars to tell the user something is happening and how long it will take. There are two visual styles: default and long (for long-running actions).

Default	Long	Purpose
		The default state for progress bars is active; and progress is shown as a percentage. For actions expected to take a long time, activity is shown with animation.
		Indeterminate state is used when an action is running but there is no way to estimate how long it will take.
		Static state - for long-running actions which are paused and can be resumed, or for progress measured across days and months rather than during the current session.
		Progress bars can be set to a range of sizes, or simply allowed to run to full width of their container.
Woooah we're halfway there	Woooah we're halfway there	Assistive and visible text can be added as well as the progress bar.
Upload timed out (512/1024k)	Upload timed out (512/1024k)	Errors - sometimes it is useful to show status information with an error.
	n/a	Page Context progress bar - a thin bar that sits at the top of the current page. Commonly used with SPAs while data is loading. Note that Page Context Progress Bars are always 100% width and thin style.

Code

Progressbar shows a percentage progress state. Application code needs to pre-calculate the value to an integer from 0 to 100 inclusive. There is a helper function in ACE for doing this in JavaScript.

Example	Element	Code
	Progress Bar set to 10% progress	HTML Classic ASP `<div class="ace-progressbar" role="progressbar" aria-valuemax="100" aria-valuemin="0" aria-valuenow="10" data-aceprogressbarstate="active"> <div class="ace-progressbar-track"> <div class="ace-progressbar-track-inner"> <div class="ace-progressbar-value"></div> </div> </div> </div>` `' Support TBA`
	Progress Bar set to indeterminate state	HTML Classic ASP `<div class="ace-progressbar" role="progressbar" data-aceprogressbarstate="indeterminate"> <div class="ace-progressbar-track"> <div class="ace-progressbar-track-inner"> <div class="ace-progressbar-value"></div> </div> </div> </div>` `' Support TBA`
	Long variant is set with a variant class.	HTML Classic ASP `<div class="ace-progressbar ace-progressbar-long" role="progressbar" data-aceprogressbarstate="indeterminate"> <div class="ace-progressbar-track"> <div class="ace-progressbar-track-inner"> <div class="ace-progressbar-value"></div> </div> </div> </div>` `' Support TBA`
	Sizes are set with a variant class. Supported sizes: `xxsmall`, `xsmall`, `small`, `medium`, `large`, `xlarge`, `xxlarge`, `fullwidth`	HTML Classic ASP `<div class="ace-progressbar ace-progressbar-long ace-progressbar-xsmall" role="progressbar" aria-valuemax="100" aria-valuemin="0" aria-valuenow="50" data-aceprogressbarstate="active"> <div class="ace-progressbar-track"> <div class="ace-progressbar-track-inner"> <div class="ace-progressbar-value"></div> </div> </div> </div>` `' Support TBA`
Uploading: 512k of 1024k	While assistive technology will generally inform the user of percentage progress, you can add alternative text using `aria-valuetext`. This can optionally be shown visibly as well; and if absoultely necessary the visible text can vary from the `aria-valuetext` (if in doubt simply match them).	HTML Classic ASP `<div class="ace-progressbar" aria-valuetext="Uploading: 512k of 1024k" role="progressbar" aria-valuemax="100" aria-valuemin="0" aria-valuenow="50" data-aceprogressbarstate="active"> <div class="ace-progressbar-text">Uploading: 512k of 1024k</div> <div class="ace-progressbar-track"> <div class="ace-progressbar-track-inner"> <div class="ace-progressbar-value"></div> </div> </div> </div>` `' Support TBA`
Upload timed out (512/1024k)	When setting an error state is it recommended that both visible and accessible text are provided with details. Note the state attribute must be set to `error`.	HTML Classic ASP `<div class="ace-progressbar" aria-valuetext="Upload timed out (512/1024k)" role="progressbar" aria-valuemax="100" aria-valuemin="0" aria-valuenow="50" data-aceprogressbarstate="error"> <div class="ace-progressbar-text">Upload timed out (512/1024k)</div> <div class="ace-progressbar-track"> <div class="ace-progressbar-track-inner"> <div class="ace-progressbar-value"></div> </div> </div> </div>` `' Support TBA`
Hidden Progress Bar	You can pre-render a hidden Progress Bar by setting the attribute `aria-hidden="true"`. You can then show it using the JavaScript `show` method.	HTML Classic ASP `<div class="ace-progressbar" id="IDOFPB" aria-hidden="true" role="progressbar" aria-valuemax="100" aria-valuemin="0" aria-valuenow="0" data-aceprogressbarstate="active"> <div class="ace-progressbar-track"> <div class="ace-progressbar-track-inner"> <div class="ace-progressbar-value"></div> </div> </div> </div>` `' Support TBA`

JavaScript

Methods

Function	Arguments	Description	Example
`setProgress`	elementSelector, options object	Sets the Progress Bar's progress percentage and state	To set a progress bar to 10% progress (`state` defaults to `active`): `ACE.Progressbar.setProgress('#IDOFPB', { 'now': 10 });` To set indeterminate state: `ACE.Progressbar.setProgress('#IDOFPB', { 'state': 'indeterminate' })` To change from indeterminate to active, update state and indicate the current progress: `ACE.Progressbar.setProgress('#IDOFPB', { 'state': 'active', 'now': '10' })` To set a Progress Bar to error state with visible and assistive text: `ACE.Progressbar.setProgress('#IDOFPB', { 'now': '33', 'text': 'Error: timed out at 33%', 'visibleText': 'Error: timed out at 33%', 'state': 'error' });`
`hide`	elementSelector	Hide a Progress Bar	`ACE.Progressbar.hide('#IDOFPB');`
`show`	elementSelector	Show a hidden Progress Bar	`ACE.Progressbar.show('#IDOFPB');`
`calculatePercent`	now, max	Helper method - calculates a simple percentage passing in the 'now' and 'max' values.	`ACE.Progressbar.calculatePercent(512, 1024) // returns 50`

Design

Code

JavaScript

Methods

Elements

Foundation

Patterns

Labs

ACE