React

This documentation will cover all React dedicated APIs provided by the Front-Commerce core.

To help you creating the best front-end with React, we've created convenient React hooks and components that you can reuse in your application.

useConditionalCallOnMount

Execute a callback when component is mounted if a condition is met.

useConditionalCallOnMount(condition, callback);

Arguments:

Name	Type	Description
condition	boolean	Specify if the callback must be executed
callback	function	A function that must be executed if condition is true

Example:

import { useConditionalCallOnMount } from "@front-commerce/core/react";

const AcmeComponent = ({ props }) => {
  const logOnMount = () => {
    console.log("I am mounted");
  };

  useConditionalCallOnMount(props.shouldLogOnMounted, logOnMount);

  return <div>Acme Component</div>;
};

useIsMount

A variable that return true or false depending of the component mount status

useIsMount();

Return: boolean

Example:

import { useIsMount } from "@front-commerce/core/react";

const AcmeComponent = ({ props }) => {
  const isMounted = useIsMount();

  return (
    <div>
      {isMounted ? "Component is mounted" : "Component isn't mounted yet"}
    </div>
  );
};

useItemsValidityCheck

caution

We recommend you to don't use this API in your application (unless you have a specific use-case that can match this method behaviour).

Return an object to tell the status of validty of an array (mostly used in the context of cart items).

useItemsValidityCheck(items);

Arguments:

Name	Type	Description
items	Array	an array of object that have a property named valid

Return

Object:

Name	Type	Description
allValidityResolved	boolean	all items contains a valid property
hasValid	boolean	array contain at least one item with valid property
allValid	boolean	all items have valid property with value true

useCallbackModal

Manage interactions with a modal and its state.

const modalCallback = useCallbackModal();

Return

Object:

Name	Type	Description
isOpen	boolean	modal state (closed or opened)
onRequestClose	function	method that must be passed as prop when modal request a close
onSuccess	function	method that must be passed as prop when modal action succeed
openCallbackModal	function	method that is the callback after modal cycle execution

Example : see useEnsureLoggedInPromise.jsx

NoPermissionProvider

Component context provider.

<NoPermissionProvider>
  <MyChildrenComponent />
</NoPermissionProvider>

Restricted

Component wrapper to prevent access to pages

<Restricted to={to}>{children}</Restricted>

Props:

Name	Type	Description
to	string	Authorisation name
children	component	Component to display

Example:

<Restricted to="acme.access">
  <Link to="acme/access">Restricted access</Link>
</Restricted>

useNoPermissions

Check if the user have the permission

Example :

const authorization = useNoPermissions();
const { isAllowedTo } = authorisation;

return <div>User authorisation status : {isAllowedTo ? "yes" : "no"}</div>;

trackPage

Not meant to be used directly, we recommend that you use useTrackPage from @front-commerce/remix instead

import { trackPage } from "@front-commerce/core/react";

function AcmePage() {
  useEffect(() => {
    trackPage("Acme Page");
  }, []);

  return <div>Acme Page</div>;
}

trackEvent

Track an event on page.

import { trackEvent } from "@front-commerce/core/react";

function AcmePage() {
  return (
    <button onClick={() => trackEvent("Acme Page click")}>Acme Page</button>
  );
}

trackIdentify

Track an identify event.

const useTrackIdentify = () => {
  const { customer, loading, anonymousId, sessionId } = useCustomer();

  useEffect(() => {
    const customer_id = customer?.id;
    const anonymous_id = anonymousId;
    const session_id = sessionId;

    if (!loading && customer_id && anonymous_id && session_id) {
      // This will track the identify event only once per session.
      trackIdentify({
        customer_id,
        anonymous_id,
        session_id,
      });
    } else {
      // This will reset the identify event, useful when the user is logged out.
      trackIdentify(undefined);
    }
  }, [loading, customer?.id, anonymousId, sessionId]);
};

usePublicConfig

Returns the public configuration of the Front-Commerce instance within a React component. This hook is designed to be used inside React components where you need to access the global configuration. It ensures the component re-renders when the configuration changes.

import { usePublicConfig } from "@front-commerce/core/react";

function PasswordHint() {
  const publicConfig = usePublicConfig();

  // Hide password hint button based on the public configuration
  if (publicConfig?.publicConfig?.password?.disablePasswordHint) {
    return null;
  }

  return <button>👁️</button>;
}

note

Prefer using usePublicConfig in React components to automatically handle updates to the configuration. It's the recommended approach to maintain reactiveness and consistency within your component tree.

getPublicConfig

Similar to usePublicConfig, this function returns the public configuration of the Front-Commerce instance. However, it's designed for use outside of React components, such as in utility functions or server-side logic where React's hook system is not available.

import { getPublicConfig } from "@front-commerce/core/react";

const publicConfig = getPublicConfig();

function validatePasswordStrength(password) {
  if (publicConfig?.publicConfig?.password?.strongPasswordRequired) {
    // Perform strong password validation
  } else {
    // Perform basic password validation
  }
}

note

Use getPublicConfig as a last resort or in scenarios where React's context is not applicable. It's ideal for server-side rendering, utility functions, or any non-React part of your application. This method will not trigger re-renders in React components.

useExtensionComponentMap

This hook is used to get the components map registered through an extension feature.

As an optional second parameter, a default value can be provided. This value will be merged with the existing components map.

import { useExtensionComponentMap } from "@front-commerce/core/react";

const AcmeModule = () => {
  const AcmeFeature = useExtensionComponentMap("acme-feature", {
    // This will be used if no `AcmeHeader` component was registered in `acme-feature` feature, or if `acme-feature` is not registered.
    AcmeHeader: () => <h1>Acme Header</h1>,
  });

  return (
    <div>
      <AcmeFeature.AcmeHeader />
      <AcmeFeature.AcmeToolbar />
      <AcmeFeature.AcmeFooter />
    </div>
  );
};

useExtensionFeatureFlags

This hook is used to get a feature flag registered through the through an extension feature.

import { useExtensionFeatureFlags } from "@front-commerce/core/react";

export function OrderFooBarPage() {
  const canOrderFooBar = useExtensionFeatureFlags(
    "order",
    "canOrderFooBar",
    false
  );

  return (
    <div>
      <h1>Order FooBar</h1>
      {canOrderFooBar ? (
        <button>Order FooBar</button>
      ) : (
        <p>You cannot order FooBar</p>
      )}
    </div>
  );
}

useCompositionComponentMap

Since version 3.11

This hook is used to get the components for a given content composition.

References

• Guide
• API

Example

import { useCompositionComponentMap } from "@front-commerce/core/react";

const AcmeModule = () => {
  const Wysiwyg = useCompositionComponentMap("Wysiwyg", {
    AcmeWysiwyg: () => <div>Acme Wysiwyg</div>,
  });

  return (
    <div>
      <Wysiwyg.DefaultWysiwyg />
      <Wysiwyg.AcmeWysiwyg />
    </div>
  );
};

CompositionComponent

Since version 3.11

Render content for a given content composition.

References

• Guide
• API

Props

Name	Type	Description
name	string	The name of the content composition to render
content	Props[]	The array of content data returned for a composition
renderComponents	function(components:ReactNode[]):ReactNode[]	A function that renders the array of react nodes
renderComponent	function(component:ReactNode<Props>):ReactNode	A function that renders a single react node

Example

<CompositionComponent
  name="SharedContent"
  content={homepage.sharedContent}
  // optional custom rendering that wraps the array of react nodes
  renderComponents={(components) => <Stack size={8}>{components}</Stack>}
  // optional custom rendering that wraps a single react node
  renderComponent={(component) => {
    if (component.props.__typename !== "Carousel") {
      // example where we don't want to wrap the carousel in a container so that it's full width
      return <div className="container">{component}</div>;
    }
    return component;
  }}
/>