Skip to main content

Contextual assistant

Contextual assistant component

Source@dopt/react-contextual-assistant

danger

This component is currently in an alpha stage.

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.

Installation

info

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

npm install @dopt/react-contextual-assistant

Usage

The default export from @dopt/react-contexutal-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 and renders the provider popover.

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

function MyContextualAssistant() {
const {
active,
setActive,
closeAssistant,
selection,
answer,
content,
documents,
} = 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.Content>
</ContextualAssistant.Popover>
)}
</>
);

}

Props

Provider

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

NameTypeDescription
defaultActive?booleanDetermines the initial visibility of the component (default: false)
assistant?stringThe Assistant in Dopt this contextual assistant is associated with
children?ReactNodeThe contents of the component
theme?ThemeA theme definition to attach to the component

Highlight

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

NameTypeDescription
scope?'window'string
selectors?string[]An array of css selectors used to determine which elements on the page can be highlighted. Defaults to ['*'].
children?ReactNodeThe contents of the component
theme?ThemeA theme definition to attach to the component

Popover

The contextual assistant popover. Extends HTMLDivElement.

NameTypeDescription
alignment?AlignmentDetermines how the component should align relative to the anchor element (default: center)
children?ReactNodeThe contents of the component
offset?numberThe distance in px to position the component relative to the anchor element (default: 10)
position?SideThe side that the component should position relative to the anchor element (default: top)
theme?ThemeA theme definition to attach to the component

Content

The contextual assistant popover's content. Extends HTMLDivElement.

NameTypeDescription
children?ReactNodeThe contents of the component
theme?ThemeA theme definition to attach to the component

The header of The contextual assistant popover. Extends HTMLElement.

NameTypeDescription
children?ReactNodeThe contents of the component
theme?ThemeA theme definition to attach to the component

Title

The title of the contextual asssistant popover. Extends HTMLHeadingElement.

NameTypeDescription
children?ReactNodeThe contents of the component
theme?ThemeA theme definition to attach to the component

DismissIcon

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

NameTypeDescription
theme?ThemeA theme definition to attach to the component

Body

The body of the contextual asssistant popover. Extends HTMLDivElement.

NameTypeDescription
children?ReactNodeThe contents of the component
theme?ThemeA theme definition to attach to the component

BodyHeading

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

NameTypeDescription
children?ReactNodeThe contents of the component
theme?ThemeA theme definition to attach to the component

Skeleton

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

NameTypeDescription
width?CSSProperties['width']The width of the element
height?CSSProperties['height']The height of the element
theme?ThemeA theme definition to attach to the component

Answer

The answer of the contextual asssistant popover. Extends HTMLDivElement.

NameTypeDescription
children?stringnull
theme?ThemeA theme definition to attach to the component

Sources

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

NameTypeDescription
children?ReactNodeThe contents of the component
theme?ThemeA theme definition to attach to the component

Source

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

NameTypeDescription
url?stringThe source url
index?numberA key given this is an element in a rendered collection
children?ReactNodeThe contents of the component
theme?ThemeA theme definition to attach to the component

Styling API

Learn more about styling and theming →

NameSelectorDescription
popover.dopt-contextual-assistant__popoverPopover element
content.dopt-contextual-assistant__contentContent container
header.dopt-contextual-assistant__headerHeader containing title and dismiss icon
title.dopt-contextual-assistant__titleTitle heading
dismissIcon.dopt-contextual-assistant__dismiss-iconDismiss icon button
body.dopt-contextual-assistant__bodyBody content
bodyHeading.dopt-contextual-assistant__body-headingBody heading
skeleton.dopt-contextual-assistant__skeletonLoading skeleton
answer.dopt-contextual-assistant__answerText answer from AI API
sources.dopt-contextual-assistant__sourcesCollection of sources matching query
source.dopt-contextual-assistant__sourceIndividual source matching query