React

Import members from @edx/frontend-platform/react

The React module provides a variety of React components, hooks, and contexts for use in an application.

Source:

Classes

ErrorBoundary

Members

(static, constant) AppContext

AppContext provides data from App in a way that React components can readily consume, even if it's mutable data. AppContext contains the following data structure:

{
  authenticatedUser: <THE App.authenticatedUser OBJECT>,
  config: <THE App.config OBJECT>
}

If the App.authenticatedUser or App.config data changes, AppContext will be updated accordingly and pass those changes onto React components using the context.

AppContext is used in a React application like any other `React Context

Source:

Methods

(static) AppProvider(props)

A wrapper component for React-based micro-frontends to initialize a number of common data/ context providers.

subscribe(APP_READY, () => {
  ReactDOM.render(
    <AppProvider>
      <HelloWorld />
    </AppProvider>
  )
});

This will provide the following to HelloWorld:

  • An error boundary as described above.
  • An AppContext provider for React context data.
  • IntlProvider for @edx/frontend-i18n internationalization
  • Optionally a redux Provider. Will only be included if a store property is passed to AppProvider.
  • A Router for react-router.
Parameters:
Name Type Description
props Object
Properties
Name Type Attributes Description
store Object <optional>

A redux store.

Source:

(static) AuthenticatedPageRoute(props)

A react-router route that redirects to the login page when the route becomes active and the user is not authenticated. If the application has been initialized with requireAuthenticatedUser false, an authenticatedPageRoute can be used to protect a subset of the application's routes, rather than the entire application.

It can optionally accept an override URL to redirect to instead of the login page.

Like a PageWrap, also calls sendPageEvent when the route becomes active.

Parameters:
Name Type Description
props Object
Properties
Name Type Description
redirectUrl string

The URL anonymous users should be redirected to, rather than viewing the route's contents.

Source:
See:
  • PageWrap
  • {@link module:frontend-platform/analytics~sendPageEvent}

(static) ErrorPage()

An error page that displays a generic message for unexpected errors. Also contains a "Try Again" button to refresh the page.

Source:

(static) LoginRedirect()

A React component that, when rendered, redirects to the login page as a side effect. Uses redirectToLogin to perform the redirect.

Source:
See:
  • {@link module:frontend-platform/auth~redirectToLogin}

(static) OptionalReduxProvider(props)

Parameters:
Name Type Description
props Object
Source:

(static) PageWrap(props)

A Wrapper component that calls sendPageEvent when it becomes active.

Parameters:
Name Type Description
props Object
Source:
See:
  • {@link module:frontend-platform/analytics~sendPageEvent}

(static) useAppEvent(type, callback)

A React hook that allows functional components to subscribe to application events. This should be used sparingly - for the most part, Context should be used higher-up in the application to provide necessary data to a given component, rather than utilizing a non-React-like Pub/Sub mechanism.

Parameters:
Name Type Description
type string
callback function
Source:

(static) useComponentPropOverrides(target, props, optionsopt) → {Record.<string, any>}

A React hook that processes the given target to extend/merge component props with any corresponding attributes/values based on configuration.

This hook looks up the specified target in the componentPropOverrides configuration, and if a match is found, it merges the component's props with the mapped attributes/values per the configured component targets.

Parameters:
Name Type Attributes Description
target string

The component target used to identify custom props per configuration.

props Record.<string, any>

The original props object passed to the component.

options ComponentPropOverridesOptions <optional>

Optional configuration for the hook.

Source:
See:
Returns:

An updated props object with custom props merged in.

Type
Record.<string, any>
Example
// Given a configuration like:
{
  componentPropOverrides: {
    targets: {
      example: {
        'data-dd-privacy': 'mask',
        'data-hj-suppress': '',
        className: 'fs-mask',
      },
    },
  },
}

// and calling the hook as follows:
const propOverrides = useComponentPropOverrides('example', { otherProp: 'value' });

// The resulting `propOverrides` will be:
{ otherProp: 'value', 'data-dd-privacy': 'mask', data-hj-suppress: '', className: 'fs-mask' }

(static) useTrackColorSchemeChoice()

A React hook that tracks user's preferred color scheme (light or dark) and sends respective event to the tracking service.

Source:

(static) withComponentPropOverrides(targetopt, optionsopt)

A Higher-Order Component (HOC) that enhances the wrapped component with custom props via the useComponentPropOverrides hook to merge any custom props from configuration with the actual component props.

Parameters:
Name Type Attributes Description
target string <optional>

The target used to identify any custom props for a given element.

options ComponentPropOverridesOptions <optional>

Optional configuration for the HOC.

Source:
See:
Example
// Given a configuration like:
{
  componentPropOverrides: {
    targets: {
      example: {
        'data-dd-privacy': 'mask',
        'data-hj-suppress': '',
        className: 'fs-mask',
      },
    },
  },
}

// and calling the HOC as follows:
const ComponentWithPropOverrides = withComponentPropOverrides('example')(MyComponent);
<ComponentWithPropOverrides otherProp="value" />

// The resulting `ComponentWithPropOverrides` will render `MyComponent` with the following props:
{ otherProp: 'value', 'data-dd-privacy': 'mask', data-hj-suppress: '', className: 'fs-mask' }