Widgets

get

The platformProps.utils.widget.get function is used to load a widget inside another widget. This function has a built-in retry mechanism. If the first request for your widget fails, it will try 2 more times.

Type

function get(
  widgetId: string,
  options?: { variantId: string; Loader: React.ReactNode }
): React.FC;

Basic usage

import { platformProps } from "@1fe/shell";

const App = (props: WidgetProps) => {
  // It's REQUIRED that you invoke widgets.get at the top of your component
  const WidgetB = platformProps.utils.widgets.get("@namespace/widget-b");

  return <WidgetB foo="bar" />;
};

Usage with Custom Loaders

You can replace the default by passing in a ReactNode. Below is an example of passing a fragment so the widget loads with no UI.

import { platformProps } from "@1fe/shell";

const App = (props: WidgetProps) => {
  // It's REQUIRED that you invoke widgets.get at the top of your component
  const WidgetB = platformProps.utils.widgets.get("@namespace/widget-b", {
    Loader: <></>,
  });

  return <WidgetB foo="bar" />;
};

Conditional rendering

import { platformProps } from "@1fe/shell";
import { checkIfWidgetBShouldRender } from "./utils";

const App = (props: WidgetProps) => {
  // It's REQUIRED that you invoke widgets.get at the top of your component
  const WidgetB = platformProps.utils.widgets.get("@namespace/widget-b");

  const shouldRenderWidgetB = checkIfWidgetBShouldRender();

  return shouldRenderWidgetB ? <WidgetB foo="bar" /> : null;
};

Usage with error boundary

While the widgets.get function has a built-in retry mechanism & error boundary, it is still possible for the widget to fail to load. The internal error boundary is set in place to handle errors and log them to our error tracking system, without influencing the UI or the parent error boundary. To provide a graceful fallback UI, you can use the ErrorBoundary component from react-error-boundary.

import { platformProps } from "@1fe/shell";
import { ErrorBoundary } from "react-error-boundary";

const ErrorFallback = ({ error, resetErrorBoundary }) => (
  <div role="alert">
    <p>Something went wrong:</p>
    <pre>{error.message}</pre>
    <button onClick={resetErrorBoundary}>Try again</button>
  </div>
);

const App = (props: WidgetProps) => {
  // It's REQUIRED that you invoke widgets.get at the top of your component
  const WidgetB = platformProps.utils.widgets.get("@namespace/widget-b");

  return (
    <ErrorBoundary FallbackComponent={ErrorFallback}>
      <WidgetB foo="bar" />
    </ErrorBoundary>
  );
};

Lifecycle

The widgets.get function will return a React Suspense component, which when mounted will trigger the loading of the widget. If the suspense isn’t mounted, the widget will not be loaded. If the widget is already loaded, the widget will be rendered immediately.

Anti-patterns

Due to the fact that widgets.get leverages React hooks internally, it is important to avoid the following anti-patterns:

1. Conditionally invoke widgets.get by either wrapping it inside of IF/ELSE statements, TRY/CATCH blocks or Null Coalescing operators.
2. Invoke widgets.get from inside of useEffect or useCallback etc. We make a special adjustment for useMemo, yet we urge you to move away from memoizing widgets.get
3. Return early before widgets.get is invoked in your React component.