@digdir/designsystemet-web

@digdir/designsystemet-web

Table of contents

• @digdir/designsystemet-web
  • Table of contents
• Get started
  • Pick the parts you need
  • Individual imports
  • Types
  • Warnings:
• <ds-breadcrumbs>
• data-clickdelegatefor
• details and summary (accessibility polyfill)
• <dialog> (closedby polyfill)
• <ds-error-summary>
• <ds-field>
  • Counter
• fieldset
• invokers (command polyfill)
• <ds-pagination>
• popover
• readonly
• <ds-suggestion>
• <ds-tabs>
• focusgroup (polyfill)
• data-tooltip

Get started

@digdir/designsystemet-web provides framework-independent behaviour for Designsystemet components. It can be used together with @digdir/designsystemet-css, with your own CSS, or as a smaller enhancement layer in an existing setup.

We recommend importing the whole package when you want all web components, observers and polyfills available globally. This will register all web components and observers globally, so you only need to do this once.

import '@digdir/designsystemet-web';

See our documentation and patterns for more guidance. Pages are also available as Markdown by appending .md to the URL or requesting Accept: text/markdown.

Pick the parts you need

Designsystemet packages are meant to be used like a toolbox. You can use the full package, or only the parts that speed up your project.

For example, you can:

• use @digdir/designsystemet-web without @digdir/designsystemet-css if you already have your own styling
• use @digdir/designsystemet-css without @digdir/designsystemet-web if you only need styles and handle interactivity yourself
• combine some Designsystemet components with your own components
• build on top of the package where it helps, and skip the parts that do not fit your setup

Individual imports

The package supports sub-path exports which means you can import individual parts of the package if needed.

import '@digdir/designsystemet-web/ds-breadcrumbs';
import '@digdir/designsystemet-web/clickdelegatefor';
import '@digdir/designsystemet-web/details';
import '@digdir/designsystemet-web/dialog';
import '@digdir/designsystemet-web/ds-error-summary';
import '@digdir/designsystemet-web/ds-field';
import '@digdir/designsystemet-web/fieldset';
import '@digdir/designsystemet-web/focusgroup';
import '@digdir/designsystemet-web/invokers';
import '@digdir/designsystemet-web/ds-pagination';
import '@digdir/designsystemet-web/popover';
import '@digdir/designsystemet-web/readonly';
import '@digdir/designsystemet-web/ds-suggestion';
import '@digdir/designsystemet-web/ds-tabs';
import '@digdir/designsystemet-web/toggle-group';
import '@digdir/designsystemet-web/tooltip';

Types

Add the package to your types for types:

{
  "compilerOptions": {
    "types": ["@digdir/designsystemet-web"]
  }
}

Warnings:

@digdir/designsystemet-web will warn you about deprecations and missing attributes. This can come in handy while developing, but can also easily be hidden, for example in production:

import '@digdir/designsystemet-web';
if (typeof window !== 'undefined' && isProduction()) window.dsWarnings = false;

<ds-breadcrumbs>

Automatically hides/shows aria-label on desktop/mobile and aria-current="page" on last link in list. No API.

<ds-breadcrumbs class="ds-breadcrumbs" aria-label="You are here:">
  <a href="#none" aria-label="Back to level 3">
    Level 3
  </a>
  <ol>
    <li><a href="#none">Level 1</a></li>
    <li><a href="#none">Level 2</a></li>
    <li><a href="#none">Level 3</a></li>
  </ol>
</ds-breadcrumbs>

data-clickdelegatefor

Used for delegating click event. For example, you can use this to delegate click events from a parent element to child elements that are added dynamically.

<div class="ds-card" data-clickdelegatefor="target">
  <a id="target" href="https://example.com" rel="noopener">Go to example</a>
  <span>Clicking this card will open example in a new tab</span>
</div>

details and summary (accessibility polyfill)

Use native elements. We polyfill a bug in Firefox when combined with Android Talkback screen reader to announce state and role properly.

<details class="ds-details">
  <summary>More info</summary>
  <div>Lorem ipsum dolor sit amet.</div>
</details>

<dialog> (closedby polyfill)

Use the native <dialog> element. We polyfill support for closedby="any".

<dialog class="ds-dialog" closedby="any" id="my-dialog">
my dialog
</dialog>

Open and close

Use invokers command and commandfor, to open and close dialog.

<button class="ds-button" type="button" command="show-modal" commandfor="my-dialog">
  Open dialog
</button>
<dialog id="my-dialog" class="ds-dialog">
  <button class="ds-button" command="close" commandfor="my-dialog">Close</button>
</dialog>

<ds-error-summary>

Automatically takes focus when visible and sets aria-labelledby to the first child heading. No API.

<ds-error-summary class="ds-error-summary">
  <h2>Summary</h2>
  <ul>
    <li><a href="#none">Error 1</a></li>
    <li><a href="#none">Error 2</a></li>
    <li><a href="#none">Error 3</a></li>
  </ul>
</ds-error-summary>

<ds-field>

Connects inputs, labels and error messages.

<ds-field class="ds-field">
  <label>Label</label>
  <input type="text" placeholder="Placeholder" class="ds-input" />
  <div class="ds-validation-message" data-field="validation">
    This is a validation message.
  </div>
</ds-field>

Counter

You can add a counter to inputs and textareas by adding the data-field="counter" attribute to a <p> element inside a ds-field.

<ds-field class="ds-field">
  <label>Label</label>
  <textarea class="ds-input"></textarea>
  <p data-field="counter" data-limit="20" data-over="%d tegn for mye" data-under="%d tegn igjen"></p>
</ds-field>

fieldset

An observer will look on fieldset element, add an id to combine children element with data-field="description" and legend into aria-labelledby on fieldset.

<fieldset>
    <legend>Delivery method</legend>
    <p data-field="description">Choose one option</p>
</fieldset>

invokers (command polyfill)

We automatically attach invokers-polyfill, which means that you get support for command and commandfor.

<ds-pagination>

Implements pagination, fills buttons with text. You can use both <a> and <button> elements inside the pagination.

If you don't pass any attributes you can implement your own logic for current page and total pages.

<ds-pagination class="ds-pagination" aria-label="Bla i sider:" data-href="?page=%d" data-current="2" data-total="100">
  <ol>
    <li><a>1</a></li>
    <li><a>2</a></li>
    <li><a>3</a></li>
    <li><a>4</a></li>
  </ol>
</ds-pagination>

popover

We use native popover functionality, but we attach an event listener that fixes placement of designsystem components.

<button class="ds-button" popovertarget="popover">Open popover</button>
<div class="ds-popover" popover id="popover" data-placement="left">
  This is some popover content. It can be very long, but it will wrap and
  stay within the viewport.
</div>

If you don't use the class ds-popover you need to add the CSS property --_ds-floating to the popover element. This can be top, bottom, left or right.

readonly

Used for fixing readonly support on select and input elements. Add aria-readonly="true" to make the element behave as readonly, which means that it will not be editable by the user or call any change events.

<select aria-readonly="true">
  <option value="1">Option 1</option>
  <option value="2">Option 2</option>
  <option value="3">Option 3</option>
</select>

<ds-suggestion>

Extends u-combobox from u-elements. See documentation for u-combobox.

<ds-field class="ds-field">
  <label>Label</label>
  <ds-suggestion class="ds-suggestion">
    <input type="search" class="ds-input" />
    <del aria-label="Fjern innhold"></del>
    <u-datalist>
      <u-option value="option-1">Option 1</u-option>
      <u-option value="option-2">Option 2</u-option>
      <u-option value="option-3">Option 3</u-option>
    </u-datalist>
  </ds-suggestion>
</ds-field>

<ds-tabs>

Extends u-tabs from u-elements. See documentation for u-tabs.

<ds-tabs class="ds-tabs">
  <ds-tablist>
    <ds-tab>Tab 1</ds-tab>
    <ds-tab>Tab 2</ds-tab>
    <ds-tab>Tab 3</ds-tab>
  </ds-tablist>
  <ds-tabpanel>Panel 1</ds-tabpanel>
  <ds-tabpanel>Panel 2</ds-tabpanel>
  <ds-tabpanel>Panel 3</ds-tabpanel>
</ds-tabs>

focusgroup (polyfill)

focusgroup is polyfilled according to upcoming specification.

<fieldset class="ds-toggle-group" focusgroup="radiogroup" aria-label="Tekstjustering" data-variant="secondary">
  <label class="ds-button">
    <input type="radio" name="alignment" value="left" checked />
    Left
  </label>
  <label class="ds-button">
    <input type="radio" name="alignment" value="center" />
    Center
  </label>
  <label class="ds-button">
    <input type="radio" name="alignment" value="right" />
    Right
  </label>
</fieldset>

Radio inputs in a focusgroup="radiogroup", like the toggle group above, are handled by toggle-group: the arrow keys move focus without selecting, and Enter selects. It also migrates the deprecated data-toggle-group attribute to focusgroup="radiogroup", with a warning.

data-tooltip

Using a single element for rendering next to elements with data-tooltip attribute. Also automatically sets aria-label or aria-description as needed. Uses native popover functionality with our popover polyfill.

<button data-placement="left" data-tooltip="left" class="ds-button">left</button>