@thoughtindustries/catalog

@thoughtindustries/catalog

The Catalog allows learners to search and browse for content. It is a central component to any online learning platform.

Table of contents:

• Catalog
• Core catalog components
  • CatalogLinkButton
  • CatalogProvider
  • HeightEqualizer
• Core catalog hooks
  • useCatalog

Catalog

The Catalog component takes a callback function to handle catalog item's add-to-queue event, and optional properties to customize the catalog like price formatting, currency formating, etc. It must be a descendent of the CatalogProvider component.

Example code

import { CatalogProvider, Catalog } from '@thoughtindustries/catalog';

export function MyComponent() {
  // ...
  const addToQueueHandler = (item) => Promise.resolve();

  return (
    <CatalogProvider ssr pathName="/catalog">
      <Catalog onAddedToQueue={addToQueueHandler} />
    </CatalogProvider>
  );
}

Props

Name	Required	Type	Description
title	No	string	The title that appears on top of the catalog.
alternateTitleDisplay	No	boolean	Option to display the alternative title.
pagination	No	(args: PaginationFnArgs) => ReactElement	An alternative view for the pagination display.
companyHasSessionLevelCustomFieldsFeature	No	boolean	Company feature flag for content hydration.
companyTimeZone	No	string	Company property to override item's timezone.
onAddedToQueue	Yes	(item: CatalogResultItem) => Promise<boolean | void>	Event handler for add to queue button for each item.
onClick	No	(evt: SyntheticEvent, item: CatalogResultItem) => void	Optional click event handler for each item.
priceFormat	No	(priceInCents: number) => string	A callback that is invoked to format monetary value with currency. It takes a number value for the price in cent unit and return the formatted value. Default value uses Intl.NumberFormat with props companyDefaultLocale and/or currencyCode to enable locale-specific currency formatting.
companyDefaultLocale	No	string	A locale value to format price when prop priceFormat is not specified. Used to speficy the locale in Intl.NumberFormat. Default to en-US.
currencyCode	No	string	A currency code value to format price when prop priceFormat is not specified. Used to speficy the currency code in Intl.NumberFormat. Default to USD.
numberOfContentItems	No	number	Specify the number of items to display in the grid view.

Core catalog components

Core catalog components are objects that contain all of business logic for the catalog concept that they represent. They're used to parse and process data.

CatalogLinkButton

The CatalogLinkButton component renders a link button that conditionally overrides the link behavior to handle client side navigation. It must be a descendent of a CatalogProvider component. This is used internally by Catalog component to handle both server and client side rendering. If you are composing own version of Catalog component for different layout and styles, this component can be useful.

Example code

import { CatalogProvider, CatalogLinkButton } from '@thoughtindustries/catalog';

function CustomCatalog() {
  // ...

  return (
    <>
      {/* // ... */}
      <CatalogLinkButton href="/catalog?page=2" />
    </>
  );
}

export function MyComponent() {
  // ...

  return (
    <CatalogProvider ssr={false} pathName="/catalog">
      <CustomCatalog />
    </CatalogProvider>
  );
}

Props

This component is inherently an HTMLAnchorElement element with only the onClick prop omitted. The component will use own onClick handler.

Related components

• CatalogProvider

Related hooks

• useCatalog

CatalogProvider

The CatalogProvider component creates a context for using a catalog. It requires an url path name and a ssr flag to handle the data fetching as well as user interactions with catalog filters. It creates relevant context values that can be accessed by any descendent component using the useCatalog hook.

You must use this component if you want to use the useCatalog hook, or if you would like to use the CatalogLinkButton component.

Example code

import { CatalogProvider } from '@thoughtindustries/catalog';

export function App() {
  return <CatalogProvider ssr pathName="/catalog">{/* Your JSX */}</CatalogProvider>;
}

Props

Name	Required	Type	Description
children	Yes	React.ReactNode	Any ReactNode elements.
pathName	Yes	string	The URL path for the catalog.
searchString	No	string	The URL search string used to initialize the catalog.
layoutId	No	string	The id of the custom catalog widget layout. Use this along with widgetId to specify the custom catalog widget created in the core platform.
widgetId	No	string	The id of the custom catalog widget. Use this along with layoutId to specify the custom catalog widget created in the core platform.
ssr	Yes	boolean	Option to render the catalog on the server side or client side. When set to true, catalog will be rendered on the server side and user interactions with the filters will cause a full page load. When set to false, catalog will be rendered on the client side and user interactions with the filters will only affect the catalog portion of the page.

Related hooks

• useCatalog

HeightEqualizer

The HeightEqualizer component is a wrapper component that calculate the maximum height from its children HeightEqualizerElement components. With the max height value, it updates all children HeightEqualizerElement components to the same value. This is used internally by Catalog component to handle catalog item height in grid view. If you are composing own version of Catalog component for different layout and styles, this component can be useful.

Example code

import { HeightEqualizer, HeightEqualizerElement } from '@thoughtindustries/catalog';

export function MyComponent() {
  // ...

  return (
    <HeightEqualizer>
      <>
        <HeightEqualizerElement key="item-1">{/* Your JSX */}</HeightEqualizerElement>
        <HeightEqualizerElement key="item-2">{/* Your JSX */}</HeightEqualizerElement>
      </>
    </HeightEqualizer>
  );
}

Props

Props for HeightEqualizer

Name	Required	Type	Description
children	Yes	ReactNode	A ReactNode element.
timeout	No	number	Time to recalculate heights.
animationSpeed	No	number	Time of animation for height change (in milliseconds).

Props for HeightEqualizerElement

Name	Required	Type	Description
children	No	ReactNode	A ReactNode element.
name	Yes	string	All heights of elements with the same name will be compared.
as	No	string	An HTML tag to be rendered as the base element wrapper. The default is div.
className	No	string	A string of styling class names to apply to the underlying element.

Core catalog hooks

Core catalog hooks are functions that allow you to use state and other methods inside catalog components.

useCatalog

The useCatalog hook provides access to the catalog context. It must be a descendent of a CatalogProvider component.

Example code

import { CatalogProvider, useCatalog } from '@thoughtindustries/catalog';

export function MyComponent() {
  return (
    <CatalogProvider ssr={false} pathName="/catalog">
      <CatalogLoader />
    </CatalogProvider>
  );
}

export function CatalogLoader() {
  const { isLoading } = useCatalog();

  if (isLoading) {
    return <>Loading data</>;
  }

  return ({/* Your JSX */});
}

Return value

The useCatalog hook returns an object with the following keys:

Name	Required	Description
params	Yes	The catalog content and metadata.
urlManager	Yes	The URL manager instance to manage URL state.
ssr	Yes	This is pass-through value for the prop ssr of CatalogProvider component.
navigateClientSideAsync	No	An async function for user interaction with the catalog filters. This value is provided for client side render.
isLoading	Yes	The loading state of data fetching. During server side render, this value is always false. During client side render, this value will reflect the data fetching loading state.
scrollToRef	No	A reference to HTMLDivElement. During client side render, browser will scroll to the top of the assigned element when fetching data.
contentWrapperRef	No	A reference to HTMLDivElement. During client side render, browser will mutate the height of the assigned element when fetching data. This will prevent flashing effect when user interface switches between catalog content and a loading indicator.

Related components

• CatalogProvider