No Preview

Sorry, but you either have no stories or none are selected somehow.

If the problem persists, check the browser console, or the terminal you've run Storybook from.

The component failed to render properly, likely due to a configuration issue in Storybook. Here are some common causes and how you can address them:

  1. Missing Context/Providers: You can use decorators to supply specific contexts or providers, which are sometimes necessary for components to render correctly. For detailed instructions on using decorators, please visit the Decorators documentation.
  2. Misconfigured Webpack or Vite: Verify that Storybook picks up all necessary settings for loaders, plugins, and other relevant parameters. You can find step-by-step guides for configuring Webpack or Vite with Storybook.
  3. Missing Environment Variables: Your Storybook may require specific environment variables to function as intended. You can set up custom environment variables as outlined in the Environment Variables documentation.

Base Classes

This library uses two main base classes that all components inherit from in order to share certain common features. Those classes are:

DtBase

This is the core base class. It provides basic functionality for localization.

Properties

PropertyDefinitionDescription
locale{ type: String }Defines the locale to be used for localization of the component. If it is not set, it will read the lang attribute of the nearest parent, defaulting to the root <html> element if no others are found.
RTL{ type: String }Sets the text direction used for localization. If it is not set, it will read the dir attribute of the nearest parent, defaulting to the root <html> element if no others are found.

Members

_proxyFocus()

Used to transfer focus to the shadow DOM when the component itself receives focus. This will use the _focusTarget to determine which shadow DOM element to focus, so that getter should be changed instead of this function when the shadow DOM is non-standard.

get _focusTarget()

Used to set which element of the shadow DOM should receive focus when the component itself receives focus. This will use the _focusTarget, so that getter should be changed instead of this function.

By default, it will find the first child in the shadow DOM and focus that element:

get _focusTarget() {
  return this.shadowRoot.children[0] instanceof Element
    ? this.shadowRoot.children[0]
    : null;
}

DtFormBase

This extends DtBase to add features specific to form components, including base styles and integration with HTML forms.

This also adds a label above the form input.

Properties

Inherits all properties from DtBase.

PropertyDefinitionDescription
name{ type: String }The name attribute used to identify an input within a form. This will be submitted with the form as the field's key.
label{ type: String }Text to be displayed in the label above the form field.

Leave this empty to not display a label.
icon{ type: String }Icon to be used beside the label. This should be a URL to an image file.

To use an embedded SVG as the icon, see the icon slot.
iconAltText{ type: String }Alt text to be added to icon image
private{ type: Boolean }Indicates if field is marked with a lock icon to indicate private fields.
privateLabel{ type: String }Tooltip text to be added to private icon.
disabled{ type: Boolean }Disables field.
required{ type: Boolean }Validates that field is not empty when form is submitted and displays error if not.
requiredMessage{ type: String }Error message to be displayed for required field validation.
touched{ type: Boolean, state: true }Internal state value not available via HTML attribute.

Indicates that the form field has been changed to use when validating form.
invalid{ type: Boolean, state: true }Internal state value not available via HTML attribute.

Indicates that the form field is not valid to use when validating form.
error{ type: String }Enables error state with error icon. This error message will be displayed.
loading{ type: Boolean }Enables display of loading indicator.
saved{ type: Boolean }Enables display of saved indicator.

Members

get _field

Identifies the form element to receive focus when the component receives focus.

get _focusTarget

Sets the focus target to _field.

_setFormValue(value)

Interacts with the form internals to set the form value that will be submitted with a standard HTML form.

_validateRequired()

Not implemented by default.

Can/should be overriden by each component to implement logic for checking if a value is entered/selected.

Example:

_validateRequired() {
  const { value } = this;
  const input = this.shadowRoot.querySelector('input');
  if (value === '' && this.required) {
    this.invalid = true;
    this.internals.setValidity({
      valueMissing: true
    }, this.requiredMessage || 'This field is required', input);
  } else {
    this.invalid = false;
    this.internals.setValidity({});
  }
}

labelTemplate()

Renders the <dt-label> element. Should be used in each component to place the label in the appropriate location.

render()

Renders the component. This should be overridden by each component.

Slots

Default

Places content after the default label.

icon-start

HTML to be displayed in place of the label icon. Use this if you want to render an SVG icon.

Example:

<dt-my-element>
  <svg slot="icon-start" xmlns="http://www.w3.org/2000/svg" width="100" height="100" viewBox="0 0 100 100"><linearGradient id="lg"><stop offset="0%" stop-color="#000000"/><stop offset="100%" stop-color="#c3c3c3"/></linearGradient><rect x="2" y="2" width="96" height="96" style="fill:url(#lg);stroke:#ffffff;stroke-width:2"/><text x="50%" y="50%" font-size="18" text-anchor="middle" alignment-baseline="middle" font-family="monospace, sans-serif" fill="#ffffff">icon</text></svg>
</dt-my-element>

CSS Properties

  • --disabled-color
  • --alert-color
  • --success-color

HasOptionsList

This is a mixin that can wrap any other base class in order to add features specific to a field that has a dropdown list of options.

Properties

Inherits all properties from the specified class, along with the following.

PropertyDefinitionDescription
value{ type: Array, reflect: true }Selected value(s) in the list
query{ type: String, state: true }Search query as typed in input area
options{ type: Array }All available options for selection
filteredOptions{ type: Array, state: true }Available options filtered by search input
open{ type: Boolean, state: true }Indicates if option list is open
canUpdate{ type:Boolean, state: true }Indicates if list of available options can be updated
activeIndex{ type: Number, state: true }Index of currently selected value
containerHeight{ type: Number, state: true }Override container height
loading{ type: Boolean }Indicates if loading indicator is displayed

Members

willUpdate

Sets the containerHeight for dropdown positioning if it hasn't been set yet

updated

Sets container width CSS variable for positioning.

_select()

Not implemented by default.

This should be overridden to implement logic to determine what the value should be upon selection of an option and dispatch the change event.

_scrollOptionListToActive()

When navigating via keyboard, keep active element within visible area of option list.

_renderOption(option, index)

Renders an individual option in the list.

_baseRenderOptions()

Renders the filtered list of options, including a loading message if options aren't yet loaded or a message that no data is available if filtered option list is empty.

_renderOptions()

Uses _baseRenderOptions() and adds a button to add a new option if allowAdd is true.