Usage #

aFP Design System components are standard HTML elements — more precisely, they are custom elements. You can use them the same way as any other HTML element. Each component has detailed documentation describing its full API, including properties, events, methods, and more.

This section will familiarize you with how to use custom elements, often called web components, if you're new to them.

Attributes & Properties #

The components have different properties which are adjustable using attributes. For example, buttons use a size attribute that is mapped to the size property, which determines the size of the button.

<afp-button size="small">Click me!</afp-button>

Some properties are boolean, which means they can only have a true/false value. To enable a boolean property, add the corresponding attribute without a value.

<afp-button disabled>Click me!</afp-button>

Events #

aFP Design System emit custom events. The AfpButton component handles the following custom events, including afp-click, afp-focus and afp-blur. For a full list of events for each component, please refer to the individual component documentation.

<afp-button>Click me!</afp-button>

<script>
  const button = document.querySelector('afp-button');
  button.addEventListener('afp-click', () => {
    console.log('button clicked');
  });
</script>

Methods #

Many components have methods that you can call to trigger various behaviours. For a full list of methods for each component, please refer to the individual component documentation. For example, you can set the focus on an input using the focus() method.

<afp-input></afp-input>

<script>
  const input = document.querySelector('afp-input');
  input.focus();
</script>

Slots #

Content is passed into components through slots. The default slot is the most commonly used one — it accepts any content that doesn't have a specific slot attribute.

For example, the default slot of a button provides its label text.

<afp-button>Click me!</afp-button>

Some components also have named slots. Fill them by adding child elements with the corresponding slot attribute. The example below shows how the slot="check-icon" attribute places the icon in the checkbox's designated slot.

<afp-checkbox>
  Custom check icon
  <afp-icon slot="check-icon" name="gear"></afp-icon>
</afp-checkbox>

Assets & Icons #

Some components, such as afp-icon, require bundled assets (e.g. SVG files). Since the path where these assets are located depends on the bundling and deployment of the host application, you need to configure the asset path at runtime.

The package @afp-design-system/core provides the setAssetPath function for this purpose. By calling it in your host application, you can define the base path where the assets can be found. This ensures that components using getAssetPath (like afp-icon) are able to correctly resolve their files.

Example #

import { setAssetPath } from '@afp-design-system/core';

// If aFP Design System assets are served from /node_modules/@afp-design-system/core/dist/ by your bundler
setAssetPath('/node_modules/@afp-design-system/core/dist/');

You can find more information about using the icons on the icons component page.

Don't Use Self-closing Tags #

aFP Design System cannot have self-closing tags. You have to close the elements like this, otherwise it wouldn't work!

<!-- Don't do this -->
<afp-input />

<!-- Always do this -->
<afp-input></afp-input>