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.
  • A theme manager for Paragon.
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 Attributes Description
redirectUrl string <optional>

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) useParagonTheme() → {Array}

A custom React hook that manages the application's theme state and injects the appropriate CSS for the theme core and theme variants (e.g., light and dark modes) into the HTML document. It handles dynamically loading the theme CSS based on the current theme variant, and ensures that the theme variant's CSS is preloaded for runtime theme switching.This is done using "alternate" stylesheets. That is, the browser will download the CSS for the non-current theme variants with a lower priority than the current one.

The hook also responds to system theme preference changes (e.g., via the prefers-color-scheme media query), and can automatically switch the theme based on the system's dark mode or light mode preference.

Source:
Returns:
  • An array containing:
  1. An object representing the current theme state.
  2. A dispatch function to mutate the app theme state (e.g., change the theme variant).
  • @example const [themeState, dispatch] = useParagonTheme(); console.log(themeState.isThemeLoaded); // true when the theme has been successfully loaded.

// Dispatch an action to change the theme variant dispatch(paragonThemeActions.setParagonThemeVariant('dark'));

Type
Array

(static) useParagonThemeCore(args)

Custom React hook that manages the loading and updating of the core Paragon theme CSS and the brand override theme CSS. It ensures that the core theme CSS (both default and brand override) is added to the document <head> as <link> elements.

The function logs and handles fallback logic in case the core theme fails to load.

Parameters:
Name Type Description
args Object

The arguments object containing theme and callback information.

Properties
Name Type Description
themeCore Object

The core theme configuration.

Properties
Name Type Attributes Description
urls.default string

The URL to the default core theme CSS.
urls.brandOverride string <optional>

The URL to the brand override theme CSS (optional).
onComplete function

A callback function that is called once both the core Paragon (default) theme and brand override theme (if provided) are complete.
Source:

(static) useParagonThemeVariants(args)

A custom React hook that manages the loading of theme variant CSS files dynamically. Adds/updates a <link> element in the HTML document to load each theme variant's CSS, setting the non-current theme variants as "alternate" stylesheets. That is, the browser will download the CSS for the non-current theme variants, but at a lower priority than the current one. This ensures that if the theme variant is changed at runtime, the new theme's CSS will already be loaded.

The hook also listens for changes in the system's preference and triggers the provided callback accordingly.

Parameters:
Name Type Description
args object

Configuration object for theme variants and related settings.

Properties
Name Type Attributes Description
themeVariants object <optional>

An object containing the URLs for each supported theme variant, e.g.: { light: { url: 'https://path/to/light.css' } }.
currentThemeVariant string <optional>

The currently applied theme variant, e.g.: light.
onComplete function

A callback function called when the theme variant(s) CSS is (are) complete.
onDarkModeSystemPreferenceChange function <optional>

A callback function that is triggered when the system's preference changes.
Source:

(static) useTrackColorSchemeChoice()

A custom React hook that listens for changes in the system's color scheme preference (via matchMedia) and sends an event with the chosen color scheme (either light or dark) to the provided tracking service. It sends an event both when the hook is first initialized (to capture the user's initial preference) and when the system's color scheme preference changes.

Source: