Async link

Async link in Storybook

Usage

Overview

The AsyncLink component provides a way to navigate to a new page or route, but only after completing certain tasks or checks first. You can use it to control when and if the user is redirected based on specific conditions or operations.

When to use

Use the AsyncLink component for:

• Checking user actions, such as making sure that a form is successfully submitted before moving to a new page.
• Loading data, ensuring that important data for the next page is loaded before navigating.
• Completing tasks like saving user actions, tracking user behavior, asking for user confirmation, or saving the current state before redirecting.

When not to use

Don't use the AsyncLink component for:

• Immediate navigation. If immediate navigation is needed without any preconditions or checks, avoid using the async link. Instead, use the link component.
• Simple navigation. If the navigation doesn't involve any asynchronous tasks, such as data loading or user actions, using an async link might introduce unnecessary complexity. Instead, use the link component.

Formatting

Anatomy

The AsyncLink component consists of the following elements:

1. Label: Descriptive text that provides context and explains where the link leads to.

Content

The AsyncLink component follows the content guidelines for the link component.

Behaviors

AsyncLink displays a loading indicator while fetching content. It consists of 3 pulsating dots. The loading indicator ensures that users are aware of ongoing activity.

AsyncLink handles errors by presenting an error message or fallback UI when necessary. Upon successful completion, it updates to display the fetched content.

Accessibility

This component has been validated to meet the WCAG 2.2 AA accessibility guidelines in its default, base configuration. This includes ensuring:

• The contrast ratio of textual elements against their background is above 4.5:1.
• Non-textual content that needs to convey meaning (like icons and focus indicators) has a contrast ratio of at least 3:1 with its adjacent colors.
• The item is operable using a keyboard, as well as using a mouse.
• Content is accessible using screen readers, such as JAWS and VoiceOver.

Accessibility conformance ultimately depends on how this component is implemented and customized. Changes made by the content author can affect accessibility. For details on our shared responsibility model, please review our full Jutro accessibility statement.

Follow the guidance below when using this component in your applications:

• Ensure that any color changes meet the required threshold of 4.5:1.
• Ensure screen readers convey the loading state and any error messages.
• Avoid using words and phrases such as “Click here” or “here” as link text. Instead, create meaningful link text that makes sense on its own.

Code

Import statement

import { AsyncLink } from '@jutro/router/';

Component contract

Make sure to understand the Design System components API surface, and the implications and trade-offs. Learn more in our introduction to the component API.

Properties

onTriggerrequired

Type

function

Description

Calls the method used to trigger the promise.

children

Type

React.ReactNode | intlMessageShape

Description

The children elements to render inside the Link.

disabled

Type

string

Description

If set to true, the link is rendered in disabled state.

failTo

Type

string

Description

The destination path when the promise is rejected.

failToMessage

Type

string

Description

The message shown when the promise is rejected. It is only shown if failTo is not provided.

message

Type

string

Description

The message shown when executing the trigger/promise.

to

Type

IntlMessageShape | { pathname?: IntlMessageShape; hash?: IntlMessageShape }

hash

Type

IntlMessageShape

Description

Hash to put in the URL.

pathname

Type

IntlMessageShape

Description

Link path.

Description

The destination path when the link is clicked. Use this for paths internal to the application.

toMessage

Type

string

Description

The message shown when the promise is resolved. It is only shown if to is not provided.

Hooks

No hooks are available for AsyncLink.

Translation keys

There are no translation keys associated to the AsyncLink component.

Escape hatches

For more information, see our documentation about escape hatches.

The following options are available:

• Design tokens
• Passing native HTML attributes
• Ref with imperative handlers
• Native event property

Examples

Check out the Usage section for details about how and when to use the AsyncLink component.

Basic AsyncLink

This example shows the basic usage of the AsyncLink component. When you click on the link, the onTrigger prop callback can return either true, false, or a promise. In this example, it shows the assigned message, "Wait...", and after two seconds this message disappears and shows the text "Submitted".

import React, { useState, useEffect } from 'react';
import { AsyncLink } from '@jutro/router/';

export const BasicAsyncLink = () => {
  const [showMessage, setShowMessage] = useState(false);
  const [message, setMessage] = useState('Submit');

  const asyncMessage = "Wait..."; 

  useEffect(() => {
    let timerId;
    if (showMessage) {
      timerId = setTimeout(() => {
        setShowMessage(false);
        setMessage('Submited');
      }, 2000);
    }
    return () => clearTimeout(timerId); // Clear the timeout when the component unmounts or showMessage changes
  }, [showMessage]);

  function clickFunction() {
    setShowMessage(true);
    setMessage(asyncMessage);
  }

  return (
    <div>
      <AsyncLink
        message={asyncMessage}
        onTrigger={clickFunction}
        to="/test"
      >
        {message}
      </AsyncLink>
    </div>
  );
};

AsyncLink Messages

You can use the props toMessage and failToMessage to show messages depending on whether the returned promise is successful or rejected.

Additionally, you can use the prop failTo to redirect to a different path in case the promise fails.

import React, { useState } from 'react';
import { AsyncLink } from '@jutro/router/';

export const MessagesAsyncLink = () => {
  const [successLinkText, setSuccessLinkText] = useState('Success link');
  const [failureLinkText, setFailureLinkText] = useState('Failure link');

  const asyncMessage = "Wait...";
  const successMessage = "Action completed successfully!";
  const failureMessage = "Action failed. Please try again.";
  const timer = 2000;

  const handleSuccess = () => {
    setSuccessLinkText(asyncMessage);

    setTimeout(() => {
      setSuccessLinkText(successMessage);
      setTimeout(() => setSuccessLinkText('Success link'), timer);
    }, 2000);
  };

  const handleFailure = () => {
    setFailureLinkText(asyncMessage);

    setTimeout(() => {
      setFailureLinkText(failureMessage);
      setTimeout(() => setFailureLinkText('Failure link'), timer);
    }, 2000);
  };

  return (
    <div>
      <div>
        <AsyncLink
          message={asyncMessage}
          toMessage={successMessage}
          failToMessage={failureMessage}
          onTrigger={handleSuccess}
          to="/async-link#asynclink-messages"
        >
          {successLinkText}
        </AsyncLink>
      </div>
      <div>
        <AsyncLink
          message={asyncMessage}
          toMessage={successMessage}
          failToMessage={failureMessage}
          onTrigger={handleFailure}
          to="/async-link#asynclink-messages"
        >
          {failureLinkText}
        </AsyncLink>
      </div>
    </div>
  );
};

Changelog

10.9.0

• A new opt-in feature was introduced that disables automatic event publishing for the AsyncLink component. You can enable this feature by adding JUTRO_DISABLE_AUTO_EVENTS_PUBLISHING=true to the .env file in the root of your Jutro application. When this is enabled, legacy components no longer publish events by default. For more information on events and how to set up new events, see the Events documentation.

10.1.0

• Added support for design tokens.