Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

@coveo/atomic-react

Package Overview
Dependencies
Maintainers
13
Versions
1763
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@coveo/atomic-react

React specific wrapper for the Atomic component library

  • 1.0.4
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
2.4K
decreased by-14.71%
Maintainers
13
Weekly downloads
 
Created
Source

Atomic React

A React component library for building modern UIs interfacing with the Coveo platform. Atomic React is a wrapper around the core Atomic web component library.

The integration of React-based projects (using JSX) with Web based components can be tricky. This project is meant to address this issue, making it possible to use Atomic web-components in a manner that feels more natural to developers familiar with React.

Installation

npm i @coveo/atomic-react

Usage

Since Atomic React is built on top of the core Atomic web-components library, the vast majority of concepts that apply to core Atomic will apply to Atomic React.

However, there are still some special considerations.

Static Assets - Languages and SVGs

For performance reasons, the generated JavaScript bundle does not automatically include static assets that are loaded on demand. This impacts language support, as well as the use of included SVG icons.

It is mandatory that you make available external assets distributed with Atomic React by including them in the public directory of your app. Without this, for example, labels in the app will appear as temporary placeholders.

The location of the public directory depends on how you build, configure and distribute your app.

For example, for any project created with Create React App, this would mean copying language and icon assets to the ./public directory.

cp -r node_modules/@coveo/atomic-react/dist/assets public/assets
cp -r node_modules/@coveo/atomic-react/dist/lang public/lang

It is important to respect the folder hierarchy, with SVG icons under the assets subdirectory, and labels and languages under the lang subdirectory of the public folder.

Result templates

Rendering different types of result templates based on the type of content returned by the Coveo platform is very common when building a Coveo search page.

The way to create result templates for an HTML project using the core Atomic library involves defining one or multiple atomic-result-template components, configured with HTML properties, adding conditions on the attributes and metadata of each results.

Coupled with the <template> HTML tag, this works very well in a pure HTML project.

However, this can be limiting and awkward to use in a React project using JSX.

Atomic React exposes an AtomicResultList component with a template property that can be used in a more straightforward manner when coupled with JSX.

The template property accepts a function with a Result parameter, which can then be used to conditionally render different templates based on properties and fields available in result items.

The template function must then simply return a valid JSX Element.

Here is an example of a fictitious search page, which defines some premade templates for YouTube videos, as well as Salesforce cases:

import {
  Result,
  AtomicResultSectionVisual,
  AtomicResultImage,
  AtomicResultSectionTitle,
  AtomicResultLink,
  AtomicResultSectionBottomMetadata,
  AtomicText,
  AtomicResultNumber,
  AtomicFormatUnit,
  AtomicResultSectionExcerpt,
  AtomicResultText,
  AtomicResultSectionEmphasized,
  AtomicSearchInterface,
  AtomicResultList,
  buildSearchEngine,
  getSampleSearchEngineConfiguration,
} from '@coveo/atomic-react';

const MyResultTemplateForYouTubeVideos: React.FC<{result: Result}> = ({
  result,
}) => {
  return (
    <>
      <AtomicResultSectionVisual>
        <AtomicResultImage field="ytthumbnailurl" />
      </AtomicResultSectionVisual>
      <AtomicResultSectionTitle>
        <AtomicResultLink />
      </AtomicResultSectionTitle>
      {result.raw.ytvideoduration !== undefined && (
        <AtomicResultSectionBottomMetadata>
          <AtomicText value="Duration" />
          <AtomicResultNumber field="ytvideoduration">
            <AtomicFormatUnit unit="minute" />
          </AtomicResultNumber>
        </AtomicResultSectionBottomMetadata>
      )}
    </>
  );
};

const MyResultTemplateForSalesforceCases: React.FC<{result: Result}> = ({
  result,
}) => {
  return (
    <>
      <AtomicResultSectionTitle>
        <AtomicResultLink />
      </AtomicResultSectionTitle>
      <AtomicResultSectionExcerpt>
        <AtomicResultText field="excerpt" />
      </AtomicResultSectionExcerpt>
      <AtomicResultSectionEmphasized>
        {result.raw.sfpriority !== undefined && (
          <>
            <AtomicText value="Priority" />
            <AtomicResultText field="sfpriority" />
          </>
        )}
        {result.raw.sfstatus !== undefined && (
          <>
            <AtomicText value="Status" />
            <AtomicResultText field="sfstatus" />
          </>
        )}
      </AtomicResultSectionEmphasized>
    </>
  );
};

const MyDefaultTemplate: React.FC<{}> = () => {
  return (
    <>
      <AtomicResultSectionTitle>
        <AtomicResultLink />
      </AtomicResultSectionTitle>
      <AtomicResultSectionExcerpt>
        <AtomicResultText field="excerpt" />
      </AtomicResultSectionExcerpt>
    </>
  );
};

const MyResultTemplateFunction = (result: Result) => {
  if (result.raw.filetype === 'YoutubeVideo') {
    return <MyResultTemplateForYouTubeVideos result={result} />;
  }

  if (result.raw.objecttype === 'Case') {
    return <MyResultTemplateForSalesforceCases result={result} />;
  }

  return <MyDefaultTemplate />;
};

const MyPage = () => {
  const engine = buildSearchEngine({
    configuration: getSampleSearchEngineConfiguration(),
  });
  return (
    <AtomicSearchInterface engine={engine}>
      <AtomicResultList template={MyResultTemplateFunction} />
    </AtomicSearchInterface>
  );
};

Styling Result Template Components

Due to the way Atomic Web components use Shadow Dom and CSS parts to provide encapsulation, it is necessary to follow these guidelines when you wish to style elements inside any result template.

Option 1 -- Using Higher-Order Components (HOC)

This option works well if you do not need to create any CSS rule that would need to target the Shadow parts of an Atomic result component.

For example, if you want to modify the color of all result links in a template to pink, you could do so like this:

import {
  AtomicResultLink,
  AtomicSearchInterface,
  AtomicResultList,
  buildSearchEngine,
  getSampleSearchEngineConfiguration,
} from '@coveo/atomic-react';

const MyStyledResultLink: React.FC<
  React.ComponentProps<typeof AtomicResultLink>
> = (props) => {
  return (
    <AtomicResultLink {...props} style={{color: 'pink'}}>
      {props.children}
    </AtomicResultLink>
  );
};

const MyPage = () => {
  const engine = buildSearchEngine({
    configuration: getSampleSearchEngineConfiguration(),
  });
  return (
    <AtomicSearchInterface engine={engine}>
      <AtomicResultList
        template={(result) => {
          return <MyStyledResultLink />;
        }}
      />
    </AtomicSearchInterface>
  );
};

This approach lets you wrap any core Atomic component inside a styled one, which you can then re-use in one or more templates. This could be done with inline styling as shown here, or with more advanced techniques such as using CSS modules.

Using React.ComponentProps<typeof AnyAtomicComponent> allows you to extract any props that the core component exposes, and augment them if need be.

Option 2 -- Using a style tag

This option works in all scenarios, and allows you to target any Shadow parts that an Atomic result component exposes, in a similar manner to using plain HTML.

The following is an example that makes the text of an AtomicResultBadge pink:

import {
  buildSearchEngine,
  getSampleSearchEngineConfiguration,
  AtomicSearchInterface,
  AtomicResultList,
  AtomicResultBadge,
} from '@coveo/atomic-react';

const myStyles = `
atomic-result-badge::part(result-badge-element) {
    color: pink;
}
`;

const MyPage = () => {
  const engine = buildSearchEngine({
    configuration: getSampleSearchEngineConfiguration(),
  });
  return (
    <AtomicSearchInterface engine={engine}>
      <AtomicResultList
        template={(result) => (
          <>
            <style>{myStyles}</style>
            <AtomicResultBadge />
          </>
        )}
      />
    </AtomicSearchInterface>
  );
};

Localization (i18n)

The Atomic React search interface component exposes an optional localization option, which takes a callback function that lets you handle localization.

import {AtomicSearchInterface} from '@coveo/atomic-react';

<AtomicSearchInterface
  localization={(i18n) => {
    i18n.addResourceBundle('en', 'translation', {
      search: "I'm feeling lucky!",
    });
  }}
></AtomicSearchInterface>;

FAQs

Package last updated on 13 Apr 2022

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc