@markprompt/react

Markprompt React

Markprompt's @markprompt/react library offers you both a simple, accessible, prebuilt React component that you can include in your codebase, as well as a set of React primitives that you can use to build your own custom Markprompt UI.

The <Markprompt /> component is built with Radix' Dialog component and allows for limited control over the Markprompt UI, mostly offering you the ability to change texts as well as how prompt references and search results are linked to your website.

The Markprompt.* primitives offer you a fully customizable way to build your own UI and have full control.

In combination with @markprompt/css, the <Markprompt /> component is a drop-in solution for most websites. You can also opt to provide your own styles, or override ours to your liking.

Installation

Install the @markprompt/react package via npm, yarn or pnpm:

# npm
npm install @markprompt/react

# yarn
yarn add @markprompt/react

# pnpm
pnpm add @markprompt/react

Usage

Example:

import `@markprompt/css`;
import { Markprompt } from '@markprompt/react';

export function Component() {
  return <Markprompt projectKey="YOUR-PROJECT-KEY" />;
}

replacing YOUR-PROJECT-KEY with the key associated to your project. It can be obtained in the project settings on Markprompt.com under "Project key".

API

<Markprompt />

The pre-built Markprompt component. It accepts the following props:

• projectKey (string): The project key associated to your project. It can be obtained in the project settings on Markprompt.com under "Project key"
• children (React.ReactNode): Trigger component, such as a search button or a floating chat bubble.
• display (plain | dialog): The way to display the content (Default: dialog)
• sticky (boolean): If true, enable user interactions outside of the dialog while keeping it open (Default: false)
• defaultView (chat | search): The default view to show (Default:
• layout (panels | tabs): Multi-pane layout when both search and chat is enabled (Default: panels)
• close (object): Options for the close modal button
• close.label (string): aria-label for the close modal button (Default: Close Markprompt)
• close.visible (boolean): Show the close button (Default: true)
• description (object): Options for the description
• description.hide (boolean): Visually hide the description (Default: true)
• description.text (string): Description text
• chat (object): Options for the chat view
• chat.enabled (boolean): Whether or not to enable the chat view (Default: true)
• chat.history (boolean): Whether or not to store conversation history and show conversation selection (Default: true)
• chat.label (string): Label for the prompt input (Default: Ask AI)
• chat.tabLabel (string): Label for the tab bar (Default: Ask AI)
• chat.placeholder (string): Placeholder for the prompt input (Default: Ask AI…)
• chat.buttonLabel (string): Label for the chat submit button (Default: Send)
• chat.showCopy (boolean): If true, show a button to copy the answer (Default: true) Ask AI…)
• chat.defaultView.message (string or ReactElement): A message or React component to show when no conversation has been initiated.
• chat.defaultView.prompts (stringp[]): A list of default prompts to show to give the user ideas of what to ask for.
• chat.apiUrl (string): URL at which to fetch completions (Default: https://api.markprompt.com/chat)
• chat.iDontKnowMessage (string): Message returned when the model does not have an answer (Default: Sorry, I am not sure how to answer that.)
• chat.model (string): The OpenAI model to use (Default: gpt-3.5-turbo)
• chat.systemPrompt (string): The prompt template (Default: You are a very enthusiastic company representative who loves to help people!)
• chat.temperature (number): The model temperature (Default: 0.1)
• chat.topP (number): The model top P (Default: 1)
• chat.frequencyPenalty (number): The model frequency penalty (Default: 0)
• chat.presencePenalty (number): The model presence penalty (Default: 0)
• chat.maxTokens (number): The max number of tokens to include in the response.
• chat.sectionsMatchCount (number): The number of sections to include in the prompt context.
• chat.sectionsMatchThreshold (number): The similarity threshold between the input question and selected sections.
• chat.tools: (ChatViewTool[]): A list of tools the model may call.
• chat.tool_choice ('auto' | 'none' | {"type": "function", "function": {"name": string}}): Controls which (if any) function is called by the model.
• chat.ToolCallsConfirmation ((props: ConfirmationProps) => JSX.Element): An optional user-provided confirmation message component that takes the tool calls provided by OpenAI and a confirm function that should be called when the user confirms the tool calls.
• chat.avatars.visible (boolean): If true, show message avatars (Default: true)
• chat.user (string | ComponentType<{ className: string }>): The user avatar. Can be a string (to use as source for the image) or a component.
• chat.assistant (string | ComponentType<{ className: string }>): The assistant avatar. Can be a string (to use as source for the image) or a component.
• feedback (object): Options for the feedback component
• feedback.enabled (boolean): Enable users to give feedback on prompt or chat answers (Default: true)
• feedback.apiUrl (string): URL at which to deliver feedback (Default: https://api.markprompt.com/feedback)
• feedback.heading (string): Heading for the feedback form, only shown in the chat view (Default: Was this response helpful?)
• feedback.onFeedbackSubmit (function): Callback when feedback is submitted
• references (object): Options for the references
• references.getHref (function): Callback to transform a reference into an href
• references.getLabel (function): Callback to transform a reference into an label to show for the link
• references.loadingText (string): Loading text (Default: Fetching context…)
• references.heading (string): Heading for the references panel (Default: Sources)
• search (object): Options for search
• search.enabled (boolean): Whether or not to enable search (Default: true)
• search.getHref (function): Callback to transform a search result into an href
• search.getHeading (function): Callback to transform a search result into a heading
• search.getTitle (function): Callback to transform a search result into a title
• search.getSubtitle (function): Callback to transform a search result into a subtitle
• search.label (string): Label for the search input, not shown but used for aria-label (Default: Search documentation)
• search.tabLabel (string): Label for the tab bar (Default: Search)
• search.placeholder (string): Placeholder for the search input (Default: Search documentation)
• search.limit (number): Maximum amount of results to return (Default: 5)
• search.apiUrl (string): URL at which to fetch search results (Default: https://api.markprompt.com/search)
• search.provider (object): A custom search provider configuration, such as Algolia
• search.askLabel (string): Label for the "Ask AI" link when using "panels" layout (Default: Ask AI)
• search.defaultView.searchesHeading (string): Section heading for default search results (Default: Recommended for you)
• search.defaultView.searches (SearchResultComponentProps[]): List of default search results, of the form { href?: string; heading?: string; title?: string; subtitle?: string;}
• trigger (object): Options for the trigger
• trigger.customElement (boolean | ReactNode): Use a custom element as the trigger. Will disable rendering any trigger element. Use openMarkprompt() to trigger the Markprompt dialog (Default: false)
• trigger.label (string): aria-label for the open button (Default: Ask AI)
• trigger.buttonLabel (string): Label for the open button (Default: Ask AI)
• trigger.placeholder (string): Placeholder text for non-floating element (Default: Ask AI)
• trigger.iconSrc (string): Custom image icon source for the open button
• title (object): Options for the title
• title.hide (boolean): Visually hide the title (Default: true)
• title.text (string): Title text (Default: Ask AI)
• linkAs (string | ComponentType): Component to use in place of <a>.

When rendering the Markprompt component, it will render a search input-like button by default. You have two other options:

• set trigger.floating = true to render a floating button
• set trigger.customElement = true, then import { openMarkprompt } from '@markprompt/react' and call openMarkprompt() from your code. This gives you the flexibility to render your own trigger element and attach whatever event handlers you would like and/or open the Markprompt dialog programmatically.

openMarkprompt()

A function to open the Markprompt dialog programmatically. Takes no arguments.

<ChatView />

A chat view component, renders a complete chat view. Can be used standalone. It accepts the following props:

• projectKey (string): The project key associated to your project. It can be obtained in the project settings on Markprompt.com under "Project key"
• activeView ("chat" | "search"): The active view (Default: undefined)
• chatOptions (object): Options for the chat view
• chatOptions.enabled (boolean): Whether or not to enable the chat view (Default: true)
• chatOptions.label (string): Label for the prompt input (Default: Ask AI)
• chatOptions.tabLabel (string): Label for the tab bar (Default: Ask AI)
• chatOptions.placeholder (string): Placeholder for the prompt input (Default: Ask AI…)
• chatOptions.apiUrl (string): URL at which to fetch completions (Default: https://api.markprompt.com/chat)
• chatOptions.iDontKnowMessage (string): Message returned when the model does not have an answer (Default: Sorry, I am not sure how to answer that.)
• chatOptions.model (string): The OpenAI model to use (Default: gpt-3.5-turbo)
• chatOptions.systemPrompt (string): The prompt template (Default: You are a very enthusiastic company representative who loves to help people!)
• chatOptions.temperature (number): The model temperature (Default: 0.1)
• chatOptions.topP (number): The model top P (Default: 1)
• chatOptions.frequencyPenalty (number): The model frequency penalty. (Default: 0)
• chatOptions.presencePenalty (number): The model presence penalty. (Default: 0)
• chatOptions.maxTokens (number): The max number of tokens to include in the response.
• chatOptions.sectionsMatchCount (number): The number of sections to include in the prompt context.
• chatOptions.sectionsMatchThreshold (number): The similarity threshold between the input question and selected sections.
• chat.tools: (OpenAI.ChatCompletionTool[]): A list of tools the model may call.
• chat.tool_choice: (OpenAI.ChatCompletionToolChoiceOption): Controls which (if any) function is called by the model.
• close: Options for the close modal button
• close.label (string): aria-label for the close modal button (Default: Close Markprompt)
• close.visible (boolean): Show the close button (Default: true)
• feedbackOptions (MarkpromptOptions['feedback']): Options for the feedback component
• feedbackOptions.enabled (boolean): Enable users to give feedback on prompt or chat answers (Default: true)
• feedbackOptions.apiUrl (string): URL at which to deliver feedback. (Default: https://api.markprompt.com/feedback)
• onDidSelectReference (function(reference: FileSectionReference): void): Callback when a reference is selected
• referencesOptions (MarkpromptOptions['references']): Options for the references
• referencesOptions.getHref (function): Callback to transform a reference into an href
• referencesOptions.getLabel (function): Callback to transform a reference into an label to show for the link
• referencesOptions.loadingText (string): Loading text (Default: Fetching context…)
• referencesOptions.heading (string): Heading for the references panel (Default: Sources)

<SearchView />

A search view component, renders a complete search view. Can be used standalone. It accepts the following props:

• projectKey (string): The project key associated to your project. It can be obtained in the project settings on Markprompt.com under "Project key"
• activeView ("chat" | "prompt" | "search"): The active view (Default: undefined)
• close: Options for the close modal button
• close.label (string): aria-label for the close modal button (Default: Close Markprompt)
• close.visible (boolean): Show the close button (Default: true)
• debug (boolean): Enable debug mode (Default: false)
• onDidSelectResult (function(): void): Callback when a search result is selected
• searchOptions (object): Options for search
• searchOptions.enabled (boolean): Whether or not to enable search. (Default: false)
• searchOptions.getHref (function): Callback to transform a search result into an href
• searchOptions.getHeading (function): Callback to transform a search result into a heading
• searchOptions.getTitle (function): Callback to transform a search result into a title
• searchOptions.getSubtitle (function): Callback to transform a search result into a subtitle
• searchOptions.label (string): Label for the search input, not shown but used for aria-label (Default: Search documentation)
• searchOptions.tabLabel (string): Label for the tab bar (Default: Search)
• searchOptions.placeholder (string): Placeholder for the search input (Default: Search documentation)
• searchOptions.limit (number): Maximum amount of results to return. (Default: 5)
• searchOptions.apiUrl (string): URL at which to fetch search results. (Default: https://api.markprompt.com/search)
• searchOptions.provider (object): A custom search provider configuration, such as Algolia

<Answer />

Render the markdown answer from the Markprompt API. It accepts the same props as react-markdown, except children.

<AutoScroller />

A component automatically that scrolls to the bottom. It accepts the following props:

• autoScroll (boolean): Whether or not to enable automatic scrolling. (Default: true)
• scrollBehaviour (string): The behaviour to use for scrolling (Default: smooth)

All other props will be passed to the underlying <div> element.

<Close />

A button to close the Markprompt dialog and abort an ongoing request. It accepts the same props as Radix UI Dialog.Close.

<Content />

The Markprompt dialog content. It accepts the same props as Radix UI Dialog.Content, with the following additional prop:

<Description />

A visually hidden aria description. It accepts the same props as Radix UI Dialog.Description, with the following additional prop:

• hide (boolean): Hide the description.

<Form />

A form which, when submitted, submits the current prompt. It accepts the same props as <form>.

<Overlay />

The Markprompt dialog overlay. It accepts the same props as Radix UI Dialog.Overlay.

<Portal />

The Markprompt dialog portal. It accepts the same props as Radix UI Dialog.Portal.

<Prompt />

The Markprompt input prompt. User input will update the prompt in the Markprompt context. It accepts the following props:

• label (ReactNode): The label for the input.
• labelClassName (string): The class name of the label element.

<References />

Render the references that Markprompt returns. It accepts the following props:

• RootComponent (Component): The wrapper component to render (Default: 'ul')
• ReferenceComponent (Component): The component to render for each reference (Default: 'li')

<Root />

The Markprompt context provider and dialog root. It accepts the Radix UI Dialog.Root props and the useMarkpromptoptions as props.

<Title />

A visually hidden aria title. It accepts the same props as Radix UI Dialog.Title, with the following additional prop:

• hide (boolean): Hide the title.

<Trigger />

A button to open the Markprompt dialog. It accepts the same props as Radix UI Dialog.Trigger.

useChat(options): UseChatResult

Create a chat prompt. It accepts the following options:

• options (UseChatOptions): Options for useChat.
  • options.chatOptions (SubmitChatOptions): Options passed to submitChat from @markprompt/core
    • chatOptions.apiUrl (string): URL at which to fetch completions. (Default: https://api.markprompt.com/chat)
    • chatOptions.frequencyPenalty (number): The model frequency penalty. (Default: 0)
    • chatOptions.iDontKnowMessage (string): Message returned when the model does not have an answer (Default: Sorry, I am not sure how to answer that.)
    • chatOptions.maxTokens (number): The max number of tokens to include in the response.
    • chatOptions.model (string): The OpenAI model to use (Default: gpt-3.5-turbo)
    • chatOptions.presencePenalty (number): The model presence penalty. (Default: 0)
    • chatOptions.sectionsMatchCount (number): The number of sections to include in the prompt context.
    • chatOptions.sectionsMatchThreshold (number): The similarity threshold between the input question and selected sections.
    • chatOptions.systemPrompt (string): The prompt template (Default: You are a very enthusiastic company representative who loves to help people!)
    • chatOptions.temperature (number): The model temperature (Default: 0.1)
    • chatOptions.topP (number): The model top P (Default: 1)
    • chatOptions.tools: (OpenAI.ChatCompletionTool[]): A list of tools the model may call.
    • chatOptions.tool_choice: (OpenAI.ChatCompletionToolChoiceOption): Controls which
  • options.debug (boolean): Enable debug mode (Default: false)
  • options.feedbackOptions (SubmitFeedbackOptions): Options for useFeedback.
    • options.apiUrl (string): URL at which to deliver feedback (Default: https://api.markprompt.com/feedback)
  • options.projectKey (string): The project key associated to your project. It can be obtained in the project settings on Markprompt.com under "Your Project > Settings > Project key"

And it returns:

• result (UseChatResult)
  • result.abort (function(): void): Abort the current chat completions request.
  • result.abortFeedbackRequest (string): Abort the current feedback request.
  • result.messages (ChatViewMessage[]): The messages of the current chat session.
  • result.promptId (string): The prompt id of the last message.
  • result.regenerateLastAnswer (function(): void): Regenerate the last answer.
  • result.submitChat (function(prompt: string): void): Submit a chat prompt.
  • result.submitFeedback (function(feedback: PromptFeedback, state: ChatLoadingState, messageIndex: number)): Submit feedback for the last answer.

useFeedback(options): UseFeedbackResult

Create a chat prompt. It accepts the following options:

• options (UseFeedbackOptions): Options for useFeedback.
  • options.debug (boolean): Enable debug mode (Default: false)
  • options.feedbackOptions (SubmitFeedbackOptions): Options for @markprompt/core's submitFeedback.
    • options.apiUrl (string): URL at which to deliver feedback (Default: https://api.markprompt.com/feedback)
  • options.projectKey (string): The project key associated to your project. It can be obtained in the project settings on Markprompt.com under "Your Project > Settings > Project key"
  • options.promptId (string): The prompt id to submit feedback for.

And it returns:

• result (UseFeedbackResult)
  • result.abort (function(): void): Abort the current feedback request.
  • result.submitFeedback (function(feedback: PromptFeedback, state: ChatLoadingState, messageIndex: number)): Submit feedback for the last answer.

useSearch(options): UseSearchResult

Create a search prompt. It accepts the following options:

• options (UseSearchOptions): Options for useSearch.
  • options.debug (boolean): Enable debug mode (Default: false)
  • options.projectKey (string): The project key associated to your project. It can be obtained in the project settings on Markprompt.com under "Your Project > Settings > Project key"
  • options.searchOptions (SubmitSearchOptions): Options for @markprompt/core's submitSearch
    • searchOptions.apiUrl (string): URL at which to fetch search results. (Default: https://api.markprompt.com/search)
    • searchOptions.limit (number): Maximum amount of results to return. (Default: 8)
    • searchOptions.provider (AlgoliaProvider): A custom search provider configuration, such as Algolia
      • provider.apiKey (string): The API key to use for the search provider
      • provider.appId (string): The app ID to use for the search provider
      • provider.indexName (string): The index name to use for the search provider
      • provider.name ("algolia"): The name of the custom provider. Currently only algolia is supported.
      • provider.searchParameters (object): Additional search parameters to pass to the search provider

And it returns:

• result (UseSearchResult): The search result
  • result.abort (function(): void): Abort the current search request.
  • result.searchQuery (string): The current search query
  • result.searchResults (SearchResultComponentProps[]): The current search results
  • result.state (SearchLoadingState): The loading state of the current search request
  • result.submitSearchQuery (function(query: string): void): Submit a search query.
  • result.setSearchQuery (function(query: string): void): Set the search query.

Documentation

The full documentation for the component can be found on the Markprompt docs.

Starter Template

For a working setup based on Next.js + Tailwind, check out the Markprompt starter template.

Community

• X
• Discord

Authors

This library is created by the team behind Markprompt (@markprompt).

License

MIT © Markprompt