Usage #

aFP Design System are just normal HTML elements. More precisely, they are user-defined elements. You can use them in the same way as any other element. Each component has detailed documentation describing its full API, including properties, events, methods and more.

This section will familiarise 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 #

Incorporating content into various components is often achieved through the use of slots. The default slot stands out as the most frequently utilised one. It accommodates any content within the component that lacks a designated slot attribute.

To illustrate, the default slot of a button serves the purpose of providing content for its label.

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

Additionally, certain components feature named slots. These slots can be filled by incorporating child elements with corresponding slot attributes. Observe how the icon below utilizes the slot="prefix" attribute. This instruction prompts the component to position the icon within its designated prefix 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>