@dopt/react-contextual-assistant v0.2.1

@dopt/react-contextual-assistant

Overview

The contextual assistant component is powered by an Assistant and is a great way for your users to learn about your product by interacting with it.

You can use the contextual assistant component as a pre-built component or break out and use it headlessly with your own UI component.

Learn more about how to use this component with Dopt →

Installation

ℹ️ If you are using a particular React framework like Next.js, please check out our framework specific docs.

# npm
npm install @dopt/react-contextual-assistant

# Yarn
yarn add @dopt/react-contextual-assistant

# pnpm
pnpm add @dopt/react-contextual-assistant

Usage

The default export from @dopt/react-contextual-assistant is a collection of components that you can use to structure and compose the contextual assistant.

There are two parts to the usage: initialization and the contextual assistant popover.

Initialization involves wrapping some sub-tree with contextual assistant's context provider and its highlight component.

import ContextualAssistant, {
  useContextualAssistant,
} from '@dopt/react-contextual-assistant';

function MyApp(props: Props) {
  return (
    <ContextualAssistant.Provider assistant="my-assistant">
      <ContextualAssistant.Highlight>
        {props.children}
      </ContextualAssistant.Highlight>
    </ContextualAssistant.Provider>
  );
}

Having initialized the contextual assistant, you can now render UI that activates it (e.g. a button in the example that renders the provider popover).

In the example below, the popover renders with loading states, answer, sources, and an input where follow-up questions can be asked. All of these elements are composable and can be removed if unwanted. Likewise, they can be replaced with your own implementations.

import ContextualAssistant, {
  useContextualAssistant,
} from '@dopt/react-contextual-assistant';

function MyContextualAssistant() {
  const {
    close,
    selection,
    setActive,
    answer,
    content,
    documents,
    submittedQuery,
    enteredQuery,
    canSubmitQuery,
    onEnteredQuery,
    submitQuery,
  } = useContextualAssistant();

  return (
    <>
      <button onClick={() => setActive((prev) => !prev)}>
        Activate AI assistant
      </button>
      {selection && (
        <ContextualAssistant.Popover
          position="right"
          alignment="start"
          anchor={selection}
        >
          <ContextualAssistant.Content>
            <ContextualAssistant.Header>
              <ContextualAssistant.Title>
                ✨ AI assistant
              </ContextualAssistant.Title>
              <ContextualAssistant.DismissIcon
                onClick={() => closeAssistant()}
              />
            </ContextualAssistant.Header>
            <ContextualAssistant.Body>
              {answer || content ? (
                <ContextualAssistant.Answer>
                  {answer || content}
                </ContextualAssistant.Answer>
              ) : (
                <div style={{ display: 'grid', gap: 8 }}>
                  <ContextualAssistant.Skeleton />
                  <ContextualAssistant.Skeleton width="85%" />
                  <ContextualAssistant.Skeleton width="95%" />
                </div>
              )}
              {documents && documents.length > 0 && (
                <>
                  <ContextualAssistant.BodyHeading>
                    Sources
                  </ContextualAssistant.BodyHeading>
                  <ContextualAssistant.Sources>
                    {documents.map(({ url, title, id }) => (
                      <ContextualAssistant.Source key={id} url={url} index={id}>
                        {title}
                      </ContextualAssistant.Source>
                    ))}
                  </ContextualAssistant.Sources>
                </>
              )}
            </ContextualAssistant.Body>
            <ContextualAssistant.Question
              canSubmitQuery={canSubmitQuery}
              onEnteredQuery={onEnteredQuery}
              submitQuery={submitQuery}
            >
              {enteredQuery}
            </ContextualAssistant.Question>
          </ContextualAssistant.Content>
        </ContextualAssistant.Popover>
      )}
    </>
  );
}

Props

Provider

The root element of the contextual asssitant. Provider the sub-components the necessary context.

Highlight

The highlight on hover interaction model for the contextual assistant. Attaches an absolutely positioned element to the body of the DOM.

Popover

The contextual assistant popover. Extends HTMLDivElement.

Content

The contextual assistant popover's content. Extends HTMLDivElement.

Header

The header of The contextual assistant popover. Extends HTMLElement.

Title

The title of the contextual assistant popover. Extends HTMLHeadingElement.

DismissIcon

The dismiss icon of the contextual assistant popover. Extends HTMLButtonElement.

Body

The body of the contextual assistant popover. Extends HTMLDivElement.

BodyHeading

The body heading of the contextual assistant popover. Extends HTMLDivElement.

Skeleton

The loading component of the contextual assistant popover. Extends HTMLDivElement.

Answer

The answer of the contextual assistant popover. Extends HTMLDivElement.

Sources

The document sources of the contextual assistant popover. Extends HTMLDivElement.

Source

A document source of the contextual assistant popover. Extends HTMLDivElement.

Question

The input where users can ask follow-up questions. Extends HTMLDivElement.

If users should not have the ability to ask follow-up questions, this component can simply not be used.

Styling API

Learn more about styling and theming →