Working with UX Toolkit Web Components

This page covers the patterns for working with UX Toolkit components in your application: setting properties, listening to events, and linking behavior between components.

Note
Studio is the canonical component reference. Studio is built directly from the web components’ source code and is always up-to-date. For the full list of properties, attributes, and events for each component, browse the component in Studio. The patterns on this page apply to every component.

For a one-line summary of each available component, see the Components in UX Toolkit section on the About UX Toolkit page.

Working with component props

UX Toolkit components are native HTML web components. You configure them using HTML attributes in the markup, just like any standard HTML element.

<mq-activate-card
  card-token="{CARD_TOKEN_HERE}"
  show-title="true"
  show-description="true"
></mq-activate-card>

A few conventions to know:

Attribute names use kebab-case in HTML (e.g., card-token, show-title).
In native webview integrations, you pass the same properties via postMessage() as componentProps, but converted to lower camelCase (e.g., cardToken, showTitle). See Working within Native Webviews.
Required vs. optional props vary by component. Refer to each component’s Properties/Attributes section in Studio.

You can also set or update properties dynamically from JavaScript:

const card = document.querySelector('mq-card');
card.setAttribute('card-token', newCardToken);

Listening to component events

A custom UI component event is emitted whenever a noteworthy action or behavior occurs within that component. You can develop your application to listen for and respond to whatever events matter to your use cases. The pattern is the same as listening to any DOM event — addEventListener on the component element, with the event name and a callback that receives the event detail:

document.querySelector('mq-card-list')
  .addEventListener('mqCardListActionHook', (e) => {
    const { type, data } = e.detail;
    // ...handle event
  });

For the list of events emitted by each component, see the Events section of that component in Studio.

Linking behavior between UI components

You can link the behavior between two UI components by adding event listeners for specific events. Example 1: Selecting a card from a list updates the card detail view. In the example below, an event listener listens for mqCardListActionHook and, when a card is selected, sets the selected card’s token on the mq-card component:

document.querySelector('mq-card-list')
  .addEventListener('mqCardListActionHook', (e) => {
    const { type, data: { cardToken } } = e.detail;
    if (type === 'CARD_SELECTED') {
      document.querySelector('mq-card')
        .setAttribute('card-token', cardToken);
    }
  });

Example 2: Opening a transaction detail in a modal from a transaction list. In the following example, an event listener listens for mqTransactionListHook. If the requested operation is to view a transaction, a <div> element is created to contain the transaction component. Your application can then display the transaction details in a modal, including the Report a problem button for disputable transactions:

document.querySelector('mq-transaction-list')
  .addEventListener('mqTransactionListHook', (e) => {
    const { type, data: { transactionToken } } = e.detail;
    if (type === 'VIEW_TRANSACTION') {
      const modalContainer = document.createElement('div');
      modalContainer.innerHTML = `
        <mq-transaction
          show-report-problem-cta="DISPUTABLE"
          transaction-token="${transactionToken}">
        </mq-transaction>
      `;
      Popper.createPopper(document.body, modalContainer, {
        placement: 'center',
      });
    }
  });

React example using `onEvent` handlers

In a React application, you can attach event listeners using a ref and useEffect. Note that React’s synthetic event system does not bridge to web component custom events automatically — you must use the underlying DOM event listener.

import { useEffect, useRef } from 'react';

function CardListWithDetail() {
  const cardListRef = useRef(null);
  const cardRef = useRef(null);

  useEffect(() => {
    const handler = (e) => {
      const { type, data: { cardToken } } = e.detail;
      if (type === 'CARD_SELECTED' && cardRef.current) {
        cardRef.current.setAttribute('card-token', cardToken);
      }
    };
    const el = cardListRef.current;
    el?.addEventListener('mqCardListActionHook', handler);
    return () => el?.removeEventListener('mqCardListActionHook', handler);
  }, []);

  return (
    <>
      <mq-card-list ref={cardListRef}></mq-card-list>
      <mq-card ref={cardRef}></mq-card>
    </>
  );
}

Tip
If you’re using TypeScript with React, you may need to declare the UX Toolkit custom elements in a .d.ts file so JSX recognizes them.

Studio — canonical component reference (props, events, live preview)
Customizing UX Toolkit — themes, card art, translations
Working within Native Webviews — embedding components in mobile webviews

Guides

Integrating Components

Working with component props

Listening to component events

Linking behavior between UI components

React example using `onEvent` handlers

​Working with component props

​Listening to component events

​Linking behavior between UI components

​React example using onEvent handlers

​Related

Working with component props

Listening to component events

Linking behavior between UI components

React example using `onEvent` handlers

Related