ProgressBar — Smart UI JavaScript API

ProgressBar — Smart UI JavaScript API

On this page + Quick start

Quick start · JavaScript

Complete starter source per framework. Run the scaffold/install command first, then replace the listed files with the full code below.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>ProgressBar - JavaScript Quick Start</title>
  <link rel="stylesheet" href="./node_modules/smart-webcomponents/source/styles/smart.default.css" />
</head>
<body>
  <smart-progress-bar id="demo-progressbar"></smart-progress-bar>

  <script type="module">
    import './node_modules/smart-webcomponents/source/modules/smart.progressbar.js';

    const el = document.getElementById('demo-progressbar');
    if (el) {

      el.min = 0;
      el.max = 100;
      el.value = 50;
      el.showProgressValue = true;

      el.addEventListener('change', (event) => console.log('change:', event.detail || event));
    }
  </script>
</body>
</html>
For AI tooling

Developer Quick Reference

Component: ProgressBar   Framework: JavaScript   Selector: smart-progress-bar

API counts: 17 properties, 0 methods, 1 events

Common properties: 0, 1, 2, 3, 4, 5

Common methods: n/a

Common events: change

Module hint: smart-webcomponents/source/modules/smart.progressbar.js

Progress indicators. It can be used to show a user how far along he/she is in a process.

Class

ProgressBar

ProgressBar

Progress indicators. It can be used to show a user how far along he/she is in a process.

Selector

smart-progress-bar

Quick picks

changedisabledvalue

Properties

AanimationSets or retrieves the current animation mode for the element. When this property is set to 'none', all animations are disabled and the element will not perform any animated transitions. Otherwise, specifying a different value enables the corresponding animation behavior.
DdisabledSpecifies whether the element is active and interactive (enabled) or inactive and unresponsive to user input (disabled). When set to true, the element is disabled and cannot be interacted with; when set to false, the element remains enabled and fully functional.
FformatFunctionA callback function that specifies how to generate or customize the label displayed on the Progress Bar. This function receives relevant data (such as the current progress value) as input and returns a string that determines the label format shown to users. Use this to personalize label content, such as displaying percentages, custom text, or additional information.
IindeterminateSets the Progress bar’s value to the indeterminate state (by assigning null), which triggers and starts the loading animation. In the indeterminate state, the Progress bar does not display a fixed value but instead shows a continuous animation to indicate ongoing activity or loading without specifying progress percentage.
IinvertedSpecifies the direction in which the Progress Bar fills as its value increases, such as left to right, right to left, top to bottom, or bottom to top.
LlocaleDefines or retrieves the current language setting for the component. This property determines which language is used for displaying text and messages, and works together with the messages property to select the appropriate localized strings. Adjusting this property updates the displayed language dynamically based on the provided message translations.
LlocalizeFormatFunctionCallback function associated with the localization module, typically invoked to handle language changes, load localized resources, or update content based on the selected locale.
MmaxDefines the highest value that the progress bar can represent, establishing the upper limit for progress tracking. This value determines when the progress bar is considered 100% complete.
MmessagesDefines an object containing string values that represent the various states of password strength (e.g., "weak", "medium", "strong"). These values can be used to display contextual feedback to users based on the evaluated strength of their password.
MminDefines the lowest allowable value for the progress bar, representing the starting point from which progress is measured. This sets the minimum boundary for the progress indicator’s range.
OorientationSpecifies whether the progress bar is displayed horizontally or vertically. Adjusting this property changes the direction in which the progress indicator fills.
RrightToLeftSpecifies or retrieves a value that determines whether the element's alignment supports right-to-left (RTL) text direction, typically used for languages such as Arabic or Hebrew. When enabled, the element's content and layout will be adjusted to accommodate RTL locales.
SshowProgressValueControls the visibility of the label for the Progress Bar. When enabled, the label will be displayed; when disabled, the label will be hidden.
TthemeSpecifies the theme that controls the visual style and appearance of the element, including aspects such as colors, fonts, and overall design. Selecting a theme customizes how the element is displayed to users.
UunfocusableIf set to true, this property prevents the element from receiving keyboard focus, making it unreachable via keyboard navigation such as the Tab key.
UunlockKeyGets or sets the unlockKey property, which serves as the authorization code required to activate and access the product’s full features.
VvalueRetrieves the current value of the progress bar or sets it to a specified value, updating the visual representation accordingly. This value typically indicates the progress of a task as a numeric value within a defined range (e.g., 0 to 100).

Events

CchangeThis event is triggered whenever the value of the associated input or component is modified by the user or via programmatic changes. It provides an opportunity to respond in real time to updates, such as validating input, updating the UI, or synchronizing data with other components.

Properties

animationSets or retrieves the current animation mode for the element. When this property is set to 'none', all animations are disabled and the element will not perform any animated transitions. Otherwise, specifying a different value enables the corresponding animation behavior."none" | "simple" | "advanced"

Sets or retrieves the current animation mode for the element. When this property is set to 'none', all animations are disabled and the element will not perform any animated transitions. Otherwise, specifying a different value enables the corresponding animation behavior.

Allowed Values

  • "none" - animation is disabled
  • "simple" - ripple animation is disabled
  • "advanced" - all animations are enabled

Default value

"advanced"

Examples

Markup and runtime examples for animation:

HTML:

<smart-progress-bar animation="none"></smart-progress-bar>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-progress-bar');
el.animation = "simple";

Read the current value:

const el = document.querySelector('smart-progress-bar');
const animation = el.animation;

disabledSpecifies whether the element is active and interactive (enabled) or inactive and unresponsive to user input (disabled). When set to true, the element is disabled and cannot be interacted with; when set to false, the element remains enabled and fully functional.boolean

Specifies whether the element is active and interactive (enabled) or inactive and unresponsive to user input (disabled). When set to true, the element is disabled and cannot be interacted with; when set to false, the element remains enabled and fully functional.

Default value

false
Try a demo showcasing the disabled property.

Examples

Markup and runtime examples for disabled:

HTML attribute:

<smart-progress-bar disabled></smart-progress-bar>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-progress-bar');
el.disabled = false;

Read the current value:

const el = document.querySelector('smart-progress-bar');
const disabled = el.disabled;

formatFunctionA callback function that specifies how to generate or customize the label displayed on the Progress Bar. This function receives relevant data (such as the current progress value) as input and returns a string that determines the label format shown to users. Use this to personalize label content, such as displaying percentages, custom text, or additional information.{(value: number): string}

A callback function that specifies how to generate or customize the label displayed on the Progress Bar. This function receives relevant data (such as the current progress value) as input and returns a string that determines the label format shown to users. Use this to personalize label content, such as displaying percentages, custom text, or additional information.

Try a demo showcasing the formatFunction property.

Examples

Markup and runtime examples for formatFunction:

HTML:

<smart-progress-bar format-function="function(value) { return value + "$" }"></smart-progress-bar>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-progress-bar');
el.formatFunction = "function(value) { return \"$\" + value }";

Read the current value:

const el = document.querySelector('smart-progress-bar');
const formatFunction = el.formatFunction;

indeterminateSets the Progress bar’s value to the indeterminate state (by assigning null), which triggers and starts the loading animation. In the indeterminate state, the Progress bar does not display a fixed value but instead shows a continuous animation to indicate ongoing activity or loading without specifying progress percentage.boolean

Sets the Progress bar’s value to the indeterminate state (by assigning null), which triggers and starts the loading animation. In the indeterminate state, the Progress bar does not display a fixed value but instead shows a continuous animation to indicate ongoing activity or loading without specifying progress percentage.

Default value

false
Try a demo showcasing the indeterminate property.

Examples

Markup and runtime examples for indeterminate:

HTML attribute:

<smart-progress-bar indeterminate></smart-progress-bar>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-progress-bar');
el.indeterminate = false;

Read the current value:

const el = document.querySelector('smart-progress-bar');
const indeterminate = el.indeterminate;

invertedSpecifies the direction in which the Progress Bar fills as its value increases, such as left to right, right to left, top to bottom, or bottom to top.boolean

Specifies the direction in which the Progress Bar fills as its value increases, such as left to right, right to left, top to bottom, or bottom to top.

Default value

false
Try a demo showcasing the inverted property.

Examples

Markup and runtime examples for inverted:

HTML attribute:

<smart-progress-bar inverted></smart-progress-bar>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-progress-bar');
el.inverted = false;

Read the current value:

const el = document.querySelector('smart-progress-bar');
const inverted = el.inverted;

localeDefines or retrieves the current language setting for the component. This property determines which language is used for displaying text and messages, and works together with the messages property to select the appropriate localized strings. Adjusting this property updates the displayed language dynamically based on the provided message translations.string

Defines or retrieves the current language setting for the component. This property determines which language is used for displaying text and messages, and works together with the messages property to select the appropriate localized strings. Adjusting this property updates the displayed language dynamically based on the provided message translations.

Default value

"en"

Examples

Markup and runtime examples for locale:

HTML:

<smart-progress-bar locale="de"></smart-progress-bar>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-progress-bar');
el.locale = "fr";

Read the current value:

const el = document.querySelector('smart-progress-bar');
const locale = el.locale;

localizeFormatFunctionCallback function associated with the localization module, typically invoked to handle language changes, load localized resources, or update content based on the selected locale.function | null

Callback function associated with the localization module, typically invoked to handle language changes, load localized resources, or update content based on the selected locale.

Examples

Markup and runtime examples for localizeFormatFunction:

HTML:

<smart-progress-bar localize-format-function="function(defaultMessage, message, messageArguments){return '...'}"></smart-progress-bar>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-progress-bar');
el.localizeFormatFunction = "function(defaultMessage, message, messageArguments){return '...'}";

Read the current value:

const el = document.querySelector('smart-progress-bar');
const localizeFormatFunction = el.localizeFormatFunction;

maxDefines the highest value that the progress bar can represent, establishing the upper limit for progress tracking. This value determines when the progress bar is considered 100% complete.number

Defines the highest value that the progress bar can represent, establishing the upper limit for progress tracking. This value determines when the progress bar is considered 100% complete.

Default value

100
Try a demo showcasing the max property.

Examples

Markup and runtime examples for max:

HTML:

<smart-progress-bar max="10"></smart-progress-bar>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-progress-bar');
el.max = 50;

Read the current value:

const el = document.querySelector('smart-progress-bar');
const max = el.max;

messagesDefines an object containing string values that represent the various states of password strength (e.g., "weak", "medium", "strong"). These values can be used to display contextual feedback to users based on the evaluated strength of their password.object

Defines an object containing string values that represent the various states of password strength (e.g., "weak", "medium", "strong"). These values can be used to display contextual feedback to users based on the evaluated strength of their password.

Default value




"en": {

"propertyUnknownType": "'{{name}}' property is with undefined 'type' member!",

"propertyInvalidValue": "Invalid '{{name}}' property value! Actual value: {{actualValue}}, Expected value: {{value}}!",

"propertyInvalidValueType": "Invalid '{{name}}' property value type! Actual type: {{actualType}}, Expected type: {{type}}!",

"elementNotInDOM": "Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.",

"moduleUndefined": "Module is undefined.",

"missingReference": "{{elementType}}: Missing reference to {{files}}.",

"htmlTemplateNotSuported": "{{elementType}}: Browser doesn't support HTMLTemplate elements.",

"invalidTemplate": "{{elementType}}: '{{property}}' property accepts a string that must match the id of an HTMLTemplate element from the DOM."

}

Examples

Markup and runtime examples for messages:

HTML:

<smart-progress-bar messages="{"de":{"propertyUnknownType":"Die Eigenschaft '{{name}}' hat ein nicht definiertes 'type'-Member!","propertyInvalidValue":"Ungultiger Eigenschaftswert '{{name}}'! Aktueller Wert: {{actualValue}}, Erwarteter Wert: {{value}}!","propertyInvalidValueType":"Ungultiger Eigenschaftswert '{{name}}'! Aktueller Wert: {{actualType}}, Erwarteter Wert: {{type}}!","elementNotInDOM":"Element existiert nicht in DOM! Bitte fugen Sie das Element zum DOM hinzu, bevor Sie eine Methode aufrufen.","moduleUndefined":"Modul ist nicht definiert.","missingReference":"{{elementType}}: Fehlender Verweis auf {{files}}.","htmlTemplateNotSuported":"{{elementType}}: Browser unterstutzt keine HTMLTemplate-Elemente.","invalidTemplate":"{{elementType}}: '{{property}}' Die Eigenschaft akzeptiert eine Zeichenfolge, die mit der ID eines HTMLTemplate-Elements aus dem DOM ubereinstimmen muss."}}"></smart-progress-bar>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-progress-bar');
el.messages = {"en":{"propertyUnknownType":"'{{name}}' property is with undefined 'type' member!","propertyInvalidValue":"Invalid '{{name}}' property value! Actual value: {{actualValue}}, Expected value: {{value}}!","propertyInvalidValueType":"Invalid '{{name}}' property value type! Actual type: {{actualType}}, Expected type: {{type}}!","elementNotInDOM":"Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.","moduleUndefined":"Module is undefined.","missingReference":"{{elementType}}: Missing reference to {{files}}.","htmlTemplateNotSuported":"{{elementType}}: Browser doesn't support HTMLTemplate elements.","invalidTemplate":"{{elementType}}: '{{property}}' property accepts a string that must match the id of an HTMLTemplate element from the DOM."}};

Read the current value:

const el = document.querySelector('smart-progress-bar');
const messages = el.messages;

minDefines the lowest allowable value for the progress bar, representing the starting point from which progress is measured. This sets the minimum boundary for the progress indicator’s range.number

Defines the lowest allowable value for the progress bar, representing the starting point from which progress is measured. This sets the minimum boundary for the progress indicator’s range.

Default value

0
Try a demo showcasing the min property.

Examples

Markup and runtime examples for min:

HTML:

<smart-progress-bar min="5"></smart-progress-bar>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-progress-bar');
el.min = 10;

Read the current value:

const el = document.querySelector('smart-progress-bar');
const min = el.min;

orientationSpecifies whether the progress bar is displayed horizontally or vertically. Adjusting this property changes the direction in which the progress indicator fills."horizontal" | "vertical"

Specifies whether the progress bar is displayed horizontally or vertically. Adjusting this property changes the direction in which the progress indicator fills.

Default value

"horizontal"

Examples

Markup and runtime examples for orientation:

HTML:

<smart-progress-bar orientation="horizontal"></smart-progress-bar>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-progress-bar');
el.orientation = "vertical";

Read the current value:

const el = document.querySelector('smart-progress-bar');
const orientation = el.orientation;

rightToLeftSpecifies or retrieves a value that determines whether the element's alignment supports right-to-left (RTL) text direction, typically used for languages such as Arabic or Hebrew. When enabled, the element's content and layout will be adjusted to accommodate RTL locales.boolean

Specifies or retrieves a value that determines whether the element's alignment supports right-to-left (RTL) text direction, typically used for languages such as Arabic or Hebrew. When enabled, the element's content and layout will be adjusted to accommodate RTL locales.

Default value

false
Try a demo showcasing the rightToLeft property.

Examples

Markup and runtime examples for rightToLeft:

HTML attribute:

<smart-progress-bar right-to-left></smart-progress-bar>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-progress-bar');
el.rightToLeft = false;

Read the current value:

const el = document.querySelector('smart-progress-bar');
const rightToLeft = el.rightToLeft;

showProgressValueControls the visibility of the label for the Progress Bar. When enabled, the label will be displayed; when disabled, the label will be hidden.boolean

Controls the visibility of the label for the Progress Bar. When enabled, the label will be displayed; when disabled, the label will be hidden.

Default value

false

Examples

Markup and runtime examples for showProgressValue:

HTML attribute:

<smart-progress-bar show-progress-value></smart-progress-bar>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-progress-bar');
el.showProgressValue = false;

Read the current value:

const el = document.querySelector('smart-progress-bar');
const showProgressValue = el.showProgressValue;

themeSpecifies the theme that controls the visual style and appearance of the element, including aspects such as colors, fonts, and overall design. Selecting a theme customizes how the element is displayed to users.string

Specifies the theme that controls the visual style and appearance of the element, including aspects such as colors, fonts, and overall design. Selecting a theme customizes how the element is displayed to users.

Default value

""

Examples

Markup and runtime examples for theme:

HTML:

<smart-progress-bar theme="blue"></smart-progress-bar>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-progress-bar');
el.theme = "red";

Read the current value:

const el = document.querySelector('smart-progress-bar');
const theme = el.theme;

unfocusableIf set to true, this property prevents the element from receiving keyboard focus, making it unreachable via keyboard navigation such as the Tab key.boolean

If set to true, this property prevents the element from receiving keyboard focus, making it unreachable via keyboard navigation such as the Tab key.

Default value

false

Examples

Markup and runtime examples for unfocusable:

HTML attribute:

<smart-progress-bar unfocusable></smart-progress-bar>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-progress-bar');
el.unfocusable = false;

Read the current value:

const el = document.querySelector('smart-progress-bar');
const unfocusable = el.unfocusable;

unlockKeyGets or sets the unlockKey property, which serves as the authorization code required to activate and access the product’s full features.string

Gets or sets the unlockKey property, which serves as the authorization code required to activate and access the product’s full features.

Default value

""

Examples

Markup and runtime examples for unlockKey:

HTML:

<smart-progress-bar unlock-key=""></smart-progress-bar>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-progress-bar');
el.unlockKey = "1111-2222-3333-4444-5555";

Read the current value:

const el = document.querySelector('smart-progress-bar');
const unlockKey = el.unlockKey;

valueRetrieves the current value of the progress bar or sets it to a specified value, updating the visual representation accordingly. This value typically indicates the progress of a task as a numeric value within a defined range (e.g., 0 to 100).number

Retrieves the current value of the progress bar or sets it to a specified value, updating the visual representation accordingly. This value typically indicates the progress of a task as a numeric value within a defined range (e.g., 0 to 100).

Default value

0
Try a demo showcasing the value property.

Examples

Markup and runtime examples for value:

HTML:

<smart-progress-bar value="5"></smart-progress-bar>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-progress-bar');
el.value = 45;

Read the current value:

const el = document.querySelector('smart-progress-bar');
const value = el.value;

Events

changeThis event is triggered whenever the value of the associated input or component is modified by the user or via programmatic changes. It provides an opportunity to respond in real time to updates, such as validating input, updating the UI, or synchronizing data with other components.CustomEvent

This event is triggered whenever the value of the associated input or component is modified by the user or via programmatic changes. It provides an opportunity to respond in real time to updates, such as validating input, updating the UI, or synchronizing data with other components.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onChange

Arguments

evCustomEvent

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Try a demo showcasing the change event.

Examples

Listen for change using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

document.querySelector('smart-progress-bar')?.addEventListener('change', (event) => {
	// event handling code goes here.
})

CSS Variables

--smart-progress-bar-default-widthvar()

Default value

"var(--smart-editor-width)"

smartProgressBar default width

--smart-progress-bar-default-heightvar()

Default value

"var(--smart-editor-height)"

smartProgressBar default height