Widget

A localizable string (May contain 'L{}' tokens which resolve in the locale file) to inject into an element which will be linked using the aria-describedby attribute.

This widget is passed as the templateData so that functions in the locale file can interrogate the widget's state.

A localizable string (May contain 'L{}' tokens which resolve in the locale file) to inject as the aria-label attribute.

This widget is passed as the templateData so that functions in the locale file can interrogate the widget's state.

Custom CSS classes to add to element. May be specified as a space separated string, or as an object in which property names with truthy values are used as the class names:

 cls : {
     'b-my-class'     : 1,
     [this.extraCls]  : 1,
     [this.activeCls] : this.isActive
 }

Applies the specified color to the widget, by setting the --b-primary CSS variable in the widgets style block.

If the supplied color starts with b-, a named color from the current theme will be used (red -> b-color-red etc.). Applied as <tag style="--b-primary: var(--b-color-<color>)">, for example:

<tag style="--b-primary: var(--b-color-red)">

When the supplied color does not start with b-, it is assumed to be a valid CSS color specification and is used as is. Applied as <tag style="--b-primary: <color>">, for example:

<tag style="--b-primary: red">

Custom CSS classes to add to the contentElement. May be specified as a space separated string, or as an object in which property names with truthy values are used as the class names:

 cls : {
     'b-my-class'     : 1,
     [this.extraCls]  : 1,
     [this.activeCls] : this.isActive
 }

The CSS class(es) to add when HTML content is being applied to this widget.

Custom style spec to add to element

Custom CSS class name suffixes to apply to the elements rendered by this widget. This may be specified as a space separated string, an array of strings, or as an object in which property names with truthy values are used as the class names.

For example, consider a Panel with a ui config like so:

 new Panel({
     text : 'OK',
     ui   : 'light'
 });

This will apply the CSS class 'b-panel-ui-light' to the main element of the panel as well as its many child elements. This allows simpler CSS selectors to match the child elements of this particular panel UI:

 .b-panel-content.b-panel-ui-light {
     background-color : #eee;
 }

Using the cls config would make matching the content element more complex, and in the presence of docked items and nested panels, impossible to target accurately.

Element (or element id) to adopt as this Widget's encapsulating element. The widget's content will be placed inside this element.

If this widget has not been configured with an id, it will adopt the id of the element in order to preserve CSS rules which may apply to the id.

Element (or the id of an element) to append this widget's element to. Can be configured, or set once at runtime. To access the element of a rendered widget, see element.

The HTML content that coexists with sibling elements which may have been added to the contentElement by plugins and features. When specifying html, this widget's element will also have the htmlCls class added to its classList, to allow targeted styling.

Object to apply to elements dataset (each key will be used as a data-attribute on the element)

The HTML to display initially or a function returning the markup (called at widget construction time).

This may be specified as the name of a function which can be resolved in the component ownership hierarchy, such as 'up.getHTML' which will be found on an ancestor Widget.

Widget id, if not specified one will be generated. Also used for lookups through Widget.getById

Element (or element id) to insert this widget before. If provided, appendTo config is ignored.

Element (or element id) to append this widget element to, as a first child. If provided, appendTo config is ignored.

The tag name of this Widget's root element

A title to display for the widget. Only in effect when inside a container that uses it (such as TabPanel)

Only valid if this Widget is floating.

How to align this element with its target when showBy is called passing a simple element as an align target.

Either a full alignment config object, or for simple cases, the edge alignment string to use.

When using a simple string, the format is '[trblc]n-[trblc]n' and it specifies our edge and the target edge plus optional offsets from 0 to 100 along the edges to align to. Also supports direction independent edges horizontally, s for start and e for end (maps to l and r for LTR, r and l for RTL).

See the showBy function for more details about using the object form.

Once set, this is stored internally in object form.

Only valid if this Widget is floating and being shown through showBy. true to show a connector arrow pointing to the align target.

Only valid if this Widget is floating. Set to true to centre the Widget in browser viewport space.

Only valid if this Widget is floating or positioned. Element, Widget or Rectangle to which this Widget is constrained.

Only valid if this Widget is floating. Set to true to be able to drag a widget freely on the page. Or set to an object with a ´handleSelector´ property which controls when a drag should start.

draggable : {
    handleSelector : ':not(button)'
}

Set to true to move the widget out of the document flow and position it absolutely in browser viewport space.

Only valid if this Widget is floating.

An object which defined which CSS style property should be animated upon hide, and how it should be animated eg:

{
   opacity: {
       to : 0,
       duration: '10s',
       delay: '0s'
   }
}

Set to 'false' to disable animation.

Only valid if this Widget is floating.

When configured as true, this widget uses isMobile to maximize itself on mobile devices.

Set to true when a widget is rendered into another widget's contentElement, but must not participate in the standard layout of that widget, and must be positioned relatively to that widget's contentElement.

Editors are positioned widgets.

Defines what to do if document is scrolled while Widget is visible (only relevant when floating is set to true). Valid values: ´null´: do nothing, ´hide´: hide the widget or ´realign´: realign to the target if possible.

Only valid if this Widget is floating.

An object which defined which CSS style property should be animated upon show, and how it should be animated eg:

{
   opacity: {
       to : 1,
       duration: '10s',
       delay: '0s'
   }
}

Set to 'false' to disable animation.

The x position for the widget.

Only valid if this Widget is floating and not aligned or anchored to an element.

The y position for the widget.

Only valid if this Widget is floating and not aligned or anchored to an element.

When this widget is a child of a Container, it will by default be participating in a flexbox layout. This config allows you to set this widget's align-self style.

Controls the placement of this widget when it is added to a panel's strips collection. Typical values for this config are 'top', 'bottom', 'left', or 'right', which cause the widget to be placed on that side of the panel's body. Such widgets are called "edge strips".

Also accepts direction neutral horizontal values 'start' and 'end'.

If this config is set to 'header', the widget is placed in the panel's header, following the title. If this config is set to 'pre-header', the widget is placed before the title. Such widgets are called "header strips".

When this widget is a child of a Container, it will by default be participating in a flexbox layout. This config allows you to set this widget's flex style. This may be configured as a single number or a <flex-grow> <flex-shrink> <flex-basis> format string. numeric-only values are interpreted as the flex-grow value.

Widget's height, used to set element style.height. Either specify a valid height string or a number, which will get 'px' appended. We recommend using CSS as the primary way to control height, but in some cases this config is convenient.

Configure with true to make widget initially hidden.

Widget's margin. This may be configured as a single number or a TRBL format string. numeric-only values are interpreted as pixels.

The element's maxHeight. Can be either a String or a Number (which will have 'px' appended). Note that like height, reading the value will return the numeric value in pixels.

The elements maxWidth. Can be either a String or a Number (which will have 'px' appended). Note that like width, reading the value will return the numeric value in pixels.

The element's minHeight. Can be either a String or a Number (which will have 'px' appended). Note that like height, reading the value will return the numeric value in pixels.

The elements minWidth. Can be either a String or a Number (which will have 'px' appended). Note that like width, reading the value will return the numeric value in pixels.

Text alignment: 'left', 'center' or 'right'. Also accepts direction neutral 'start' and 'end'.

Applied by adding a b-text-align-xx class to the widgets element. Blank by default, which does not add any alignment class.

To be compliant with RTL, 'left' yields same result as 'start' and 'right' as 'end'.

A widgets weight determines its position among siblings when added to a Container. Higher weights go further down.

Widget's width, used to set element style.width. Either specify a valid width string or a number, which will get 'px' appended. We recommend using CSS as the primary way to control width, but in some cases this config is convenient.

When this Widget configuration is used in the Grid's RowExpander feature's widget config, provide the field on the expanded record to use for populating this widget's store (if applicable)

The name of the property to set when a single value is to be applied to this Widget. Such as when used in a grid WidgetColumn, this is the property to which the column's field is applied.

Disable or enable the widget. It is similar to readOnly except a disabled widget cannot be focused, uses a different rendition (usually greyish) and does not allow selecting its value.

Set to 'inert' to also set the inert DOM attribute.

An object specifying attributes to assign to the root element of this widget. Set null value to attribute to remove it.

new Label({
    elementAttributes : {
       'data-role': 'primary', // Add data-role attribute with `"primary"` value
       inert : '',             // Add inert with no value
       title : null            // This will remove the title attribute from the element
    }
});

Determines if the widgets read-only state should be controlled by its parent.

When set to true, setting a parent container to read-only will not affect the widget. When set to false, it will affect the widget.

This config object contains the defaults for the Mask created for the masked config. Any properties specified in the masked config will override these values.

Set to true to apply the default mask to the widget. Alternatively, this can be the mask message or a Mask config object.

When this is configured as true a ResizeObserver is used to monitor this element for size changes caused by either style manipulation, or by CSS layout.

By default, notifications are queued up for delivery in the next microtask.

To receive notifications immediately, set the immediate option to true.

Size changes are announced using the resize event.

The owning Widget of this Widget. If this Widget is directly contained (that is, it is one of the items of a Container), this config will be ignored. In this case the owner is always the encapsulating Container.

If this Widget is floating, this config should be specified by the developer.

Registering with an owner creates a lifecycle relationship with that owning Widget. When the owner is destroyed this widget will also be destroyed.

This also allows focus to be tracked in the ownership tree. If a widget owns another widget, then even if that other widget is in a different element, focusing that owned widget will not cause a focusOut event, and the containsFocus property remains set.

A widget can unregister from its owner and break this relationship at any time by setting the property to null. It is then the developer's responsibility to ensure that this Widget is destroyed.

Prevent tooltip from being displayed on touch devices. Useful for example for buttons that display a menu on click etc, since the tooltip would be displayed at the same time.

Whether this widget is read-only. This is only valid if the widget is an input field, or contains input fields at any depth.

All descendant input fields follow the widget's setting. If a descendant widget has a readOnly config, that is set.

An identifier by which this widget will be registered in the widgetMap of all ancestor containers.

If omitted, this widget will be registered using its id. In most cases ref is preferable over id since id is required to be globally unique while ref is not.

The ref value is also added to the elements dataset, to allow targeting it using CSS etc.

Configure as true to have the component display a translucent ripple when its focusElement, or element is tapped if the current theme supports ripples. Out of the box, only the Material theme supports ripples.

This may also be a config object containing the properties listed below.

E.g.

   columns  : [{}...],
   ripple   : {
       color : 'red',
       clip  : '.b-grid-row'
   },
   ...

If you are rendering this widget to a shadow root inside a web component, set this config to the shadowRoot. If not inside a web component, set it to document.body

Set to false to not show the tooltip when this widget is disabled

A configuration for the tab created for this widget when it is placed in a TabPanel. For example, this config can be used to control the icon of the tab for this widget:

 items : {
     panel : {
         type : 'panel',
         // other configs...

         tab : {
             icon : 'fa-wrench'
         }
     },
     ...
 }

Another use for this config is to set the tab's rotate value differently than the default managed by the TabPanel:

 items : {
     panel : {
         type : 'panel',
         // other configs...

         tab : {
             rotate : false   // don't rotate even if tabBar is docked left or right
         }
     },
     ...
 }

Set this to false to prevent the creation of a tab for this widget. In this case, this widget must be shown explicitly. The activeTab for the tab panel will be -1 in this situation.

 items : {
     panel : {
         type : 'panel',
         tab  : false,    // no tab for this item

         // other configs...
     },
     ...
 ]

Tooltip for the widget, either as a string or as a Tooltip config object.

By default, the Widget will use a single, shared instance to display its tooltip as configured, reconfiguring it to the specification before showing it. Therefore, it may not be permanently mutated by doing things such as adding fixed event listeners.

To have this Widget own its own Tooltip instance, add the property newInstance : true to the configuration. In this case, the tooltip's owner will be this Widget.

Note that in the absence of a configured ariaDescription, the tooltip's value will be used to populate an aria-describedBy element within this Widget.

Set to false to not call onXXX method names (e.g. onShow, onClick), as an easy way to listen for events.

const container = new Container({
    callOnFunctions : true

    onHide() {
         // Do something when the 'hide' event is fired
    }
});

Programmatic control over which column to start in when used in a grid layout.

Check for CSS compatibility issues when upgrading to v7. Performs the following checks:

• Detects usage of .b-fa class for icons. FontAwesome is no longer built-in, the standard .fa class should be used instead.
• Detects missing FontAwesome font. With FontAwesome no longer built-in, this must be included separately by the app.
• Checks for presence of a Bryntum theme. Theme and structural CSS has been separated, both structural CSS and a theme must be included.

Defaults to true in Grid, Scheduler, Scheduler Pro, Gantt, Calendar and TaskBoard.

Programmatic control over how many columns to span when used in a grid layout.

Specifies whether (and optionally in which axes) a Widget may scroll. true means this widget may scroll in both axes. May be an object containing boolean overflowX and overflowY properties which are applied to CSS style properties overflowX and overflowY. If they are boolean, they are translated to CSS overflow properties thus:

• true -> 'auto'
• false -> 'hidden'

After initialization, this property yields a Scroller which may be used to both set and read scroll information.

A Widget uses its overflowElement property to select which element is to be scrollable. By default, in the base Widget class, this is the Widget's encapsulating element. Subclasses may implement get overflowElement to scroll inner elements.

This property yields true if the currently focused element has been reached through other means than mouse click. If the activeElement matches :focus-visible.

Custom CSS classes to add to element. May be specified as a space separated string, or as an object in which property names with truthy values are used as the class names:

 cls : {
     'b-my-class'     : 1,
     [this.extraCls]  : 1,
     [this.activeCls] : this.isActive
 }

Element (or the id of an element) to append this widget's element to. Can be configured, or set once at runtime. To access the element of a rendered widget, see element.

Set HTML content safely, without disturbing sibling elements which may have been added to the contentElement by plugins and features. When specifying html, this widget's element will also have the htmlCls added to its classList, to allow targeted styling.

The child element into which content should be placed. This means where html should be put, or, for Containers, where child items should be rendered.

Get widgets elements dataset or assign to it

Get this widget's encapsulating HTMLElement, which is created along with the widget but added to DOM at render time.

Returns this widget's focusElement if that element can currently be given focus (e.g., this widget is not disabled, or hidden).

Get this widget's primary focus holding element if this widget is itself focusable, or contains focusable widgets.

The HTML to display initially or a function returning the markup (called at widget construction time).

This may be specified as the name of a function which can be resolved in the component ownership hierarchy, such as 'up.getHTML' which will be found on an ancestor Widget.

Get/set widgets id

Element (or element id) to insert this widget before. If provided, appendTo config is ignored.

Element (or element id) to append this widget element to, as a first child. If provided, appendTo config is ignored.

The child element which scrolls if any. This means the element used by the scrollable.

Get/set widgets elements style. The setter accepts a cssText string or a style config object, the getter always returns a CSSStyleDeclaration

Returns an [x, y] array containing the width and height of the anchor arrow used when aligning this Widget to another Widget or element.

The height is the height of the arrow when pointing upwards, the width is the width of the baseline.

Only valid if this Widget is floating.

When configured as true, this widget uses isMobile to maximize itself on mobile devices.

Moves this Widget to the desired x position.

Only valid if this Widget is floating and not aligned or anchored to an element.

Moves this Widget to the desired y position.

Only valid if this Widget is floating and not aligned or anchored to an element.

Get/set this widget's align-self flexbox setting. This may be set to modify how this widget is aligned within the cross axis of a flexbox layout container.

Get element's flex property. This may be configured as a single number or a format string:

 <flex-grow> <flex-shrink> <flex-basis>

Numeric-only values are interpreted as the flex-grow value.

Get element's offsetHeight or sets its style.height, or specified height if element no created yet.

Get element's margin property. This may be configured as a single number or a TRBL format string. numeric-only values are interpreted as pixels.

Get/set element's maxHeight. Getter returns max-height from elements style, which is always a string. Setter accepts either a String or a Number (which will have 'px' appended). Note that like height, reading the value will return the numeric value in pixels.

Get/set elements maxWidth. Getter returns max-width from elements style, which is always a string. Setter accepts either a String or a Number (which will have 'px' appended). Note that like width, reading the value will return the numeric value in pixels.

Get/set element's minHeight. Getter returns min-height from elements style, which is always a string. Setter accepts either a String or a Number (which will have 'px' appended). Note that like height, reading the value will return the numeric value in pixels.

Get/set elements minWidth. Getter returns min-width from elements style, which is always a string. Setter accepts either a String or a Number (which will have 'px' appended). Note that like width, reading the value will return the numeric value in pixels.

Accessor to the Scroller which can be used to both set and read scroll information.

Get elements offsetWidth or sets its style.width, or specified width if element not created yet.

An object providing the record and column for a widget embedded inside a WidgetColumn

columns : [
   {
       type   : 'widget',
       widgets: [{
           type     : 'button',
           icon     : 'fa fa-trash',
           onAction : ({ source : btn }) => btn.cellInfo.record.remove()
       }]
   }
]

Get/set element's disabled state. Set to 'inert' to also set the inert DOM attribute.

Get/set element's readOnly state. This is only valid if the widget is an input field, or contains input fields at any depth. Updating this property will trigger a readOnly event.

All descendant input fields follow the widget's setting. If a descendant widget has a readOnly config, that is set.

An identifier by which this widget will be registered in the widgetMap of all ancestor containers.

If omitted, this widget will be registered using its id. In most cases ref is preferable over id since id is required to be globally unique while ref is not.

The ref value is also added to the elements dataset, to allow targeting it using CSS etc.

The tab created for this widget when it is placed in a TabPanel.

Get/set a tooltip on the widget. Accepts a string or tooltip config (specify true (or 'true') to use placeholder as tooltip). When using a string it will configure the tooltip with textContent: true which enforces a default max width.

By default, this uses a singleton Tooltip instance which may be accessed from the Widget class under the name Widget.tooltip. This is configured according to the config object on pointer over.

To request a separate instance be created just for this widget, add newInstance : true to the configuration.

Class name getter. Used when original ES6 class name is minified or mangled during production build. Should be overridden in each class which extends Widget or it descendants.

class MyNewClass extends Widget {
    static $name = 'MyNewClass';
}

Programmatic control over which column to start in when used in a grid layout.

By default, on touch devices, a two finger pinch gesture where both touch points are within a Bryntum widget is converted to a CTRL/wheel event injected at the mid-point between the two initial touches.

This is so that Scheduler and Calendar views which are configured to zoomOnMouseWheel will zoom on pinch on touch devices.

That disables the platform's native pinch-zooming. Set this static flag to false to disable the conversion:

    Widget.convertPinchToMousewheel = false;

Programmatic control over how many columns to span when used in a grid layout.

The shared Tooltip instance which handles tooltips which are not configured with newInstance : true.

Widget name alias which you can use in the items of a Container widget.

class MyWidget extends Widget {
    static get type() {
       return 'mywidget';
    }
}

const panel = new Panel({
   title : 'Cool widgets',
   items : {
      customWidget : { type : 'mywidget', html : 'Lorem ipsum dolor sit amet...' }
   }
});

Get/set the widget hidden state.

Note: hidden : false does not mean that this widget is definitely visible. To ascertain visibility, use the isVisible property.

Determines visibility by checking if the Widget is hidden, or any ancestor is hidden and that it has an element which is visible in the DOM

This property is set to true when focus is within the ownership tree of this Widget.

This means that either the DOM of this widget contains focus, or, any widget DOM who's owner axis leads to this widget contains focus.

For example a DateField with its DatePicker open and being interacted with will still have containsFocus set.

Get this Widget's next sibling in the parent Container, or, if not in a Container, the next sibling widget in the same parentElement.

The owning Widget of this Widget. If this Widget is directly contained (i.e. it is one of the items of a Container), this property will be read-only, and will refer to the containing Widget.

If this property has not been set and this is a Popup with a forElement, this config will refer to that element's encapsulating Widget.

If this Widget is floating, this property should be set by the developer.

Registering with an owner creates a lifecycle relationship with that owning Widget. When the owner is destroyed this widget will also be destroyed.

A widget can unregister from its owner and break this relationship at any time by setting the property to null. It is then the developer's responsibility to ensure that this Widget is destroyed.

Get this Widget's parent when used as a child in a Container,

Get this Widget's previous sibling in the parent Container, or, if not in a Container, the previous sibling widget in the same parentElement.

If this Widget is floating or positioned, and visible, aligns the widget according to the passed specification. To stop aligning, call this method without arguments.

Moves this Widget to the x,y position. Both arguments can be omitted to just set one value.

For floating Widgets, this is a position in the browser viewport. For positioned Widgets, this is a position in the element it was rendered into.

Show aligned to another target element or Widget or Rectangle

Only valid for floating Widgets. Moves to the front of the visual stacking order.

Creates a new widget instance based on the passed config object. The config object is require to have a type property which determines what kind of widget to create.

Call once per class for custom widgets to have them register with the Widget class, allowing them to be created by type.

For example:

class MyWidget extends Widget {
  static get type() {
    return 'mywidget';
  }
}
MyWidget.initClass();

Attached a tooltip to the specified element.

Widget.attachTooltip(element, {
  text: 'Useful information goes here'
});

Returns the Widget which owns the passed element (or event).

Returns the Widget which owns the passed CSS selector.

const button = Widget.fromSelector('#my-button');

Returns the widget with the specified id.

Announces a text message that can be parsed by assistive technologies using an aria-live element.

Returns a createElement config object that defines this widget's DOM structure. This object should be determined using configurable properties to ensure this method is called again if these properties are modified.

For more information see class documentation.

Disable the widget

Enable the widget

Exits fullscreen mode

Focuses this widget if it has a focusable element.

Mask the widget, showing the specified message

Calling this delayable method marks this widget as dirty. The DOM will be updated on the next animation frame:

 widget.recompose();

 console.log(widget.recompose.isPending);
 > true

A pending update can be flushed by calling flush() (this does nothing if no update is pending):

 widget.recompose.flush();

This can be combined in one call to force a DOM update without first scheduling one:

 widget.recompose.now();

Requests fullscreen display for this widget

If this Widget contains focus, focus is reverted to the source from which it entered if possible, or to a close relative if not.

Unmask the widget

Hide widget

Shows this widget

Starts with this Widget, then Looks up the owner axis to find an ancestor which matches the passed selector. The selector may be a widget type identifier, such as 'grid', or a function which will return true when passed the desired ancestor.

Returns true if this widget is or contains the specified element or widget.

Iterate over all ancestors of this widget.

Note: Due to this method aborting when the function returns false, beware of using short form arrow functions. If the expression executed evaluates to false, iteration will terminate.

Iterate over all widgets owned by this widget and any descendants.

Note: Due to this method aborting when the function returns false, beware of using short form arrow functions. If the expression executed evaluates to false, iteration will terminate.

Returns true if this Widget owns the passed Element, Event or Widget. This is based on the widget hierarchy, not DOM containment. So an element in a Combo's dropdown list will be owned by the Combo.

Returns the first descendant widgets which the passed filter function returns true for.

Analogous to document.querySelector, finds the first Bryntum widget matching the passed selector. Supported selector formats:

• Widget type (lowercased class name): 'grid', 'scheduler', 'gantt'
• ID selector: '#myWidgetId'
• Attribute selector: '[ref=myRef]', '[customProp=value]'
• Filter function returning true for matching widgets

Widget.query('grid').destroy();
Widget.query('#myScheduler');
Widget.query('[ref=timeline]');
Widget.query(widget => widget.isCool);

Returns an array of all descendant widgets which the passed filter function returns true for.

Analogous to document.querySelectorAll, finds all Bryntum widgets matching the passed selector. Supported selector formats:

• Widget type (lowercased class name): 'grid', 'scheduler', 'gantt'
• ID selector: '#myWidgetId'
• Attribute selector: '[ref=myRef]', '[customProp=value]'
• Filter function returning true for matching widgets

Widget.queryAll('field', true);
Widget.queryAll('[customProp=someValue]');

Looks up the owner axis to find an ancestor which matches the passed selector. The selector may be a widget type identifier, such as 'grid', or a function which will return true when passed the desired ancestor.