Custom Components

Touchpoint custom components let you render structured content from NLX modalities and send user selections back to NLX. You can build components in two ways:

  • JSX (bundled apps)

  • HTML template tag (no-build) via nlxai.touchpointUi.html

How it fits together

  • In NLX Platform, define a Modality with a schema.

  • In your client application, implement a component that receives { data, conversationHandler }.

  • Register it under customModalities keyed by the Modality name.

  • Use Touchpoint UI building blocks: Typography, Buttons, CustomCard, Carousel, DateInput.

Quickstart

<script>
  const { html, React } = nlxai.touchpointUi;
  const SimpleComponent = ({ data, conversationHandler }) =>
    html`<BaseText>${data.message}</BaseText>`;

  const touchpoint = await create({
    config: {
      applicationUrl: "YOUR_APPLICATION_URL",
      headers: { "nlx-api-key": "YOUR_API_KEY" },
      languageCode: "en-US",
    },
    customModalities: {
      SimpleModality: SimpleComponent,
    },
  });
</script>

Component contract

Each component receives:

  • data: matches the Modality schema

  • conversationHandler: use to send sendChoice, sendSlots, or messages

State and events

const SelectableCard = ({ data, conversationHandler }) => {
  const [isSelected, setIsSelected] = React.useState(false);

  return html`
    <CustomCard
      selected=${isSelected}
      onClick=${() => {
        setIsSelected(true);
        conversationHandler.sendChoice(data.id);
      }}
    >
      <CustomCardRow
        left=${html`<BaseText faded>Status</BaseText>`}
        right=${html`<BaseText>${isSelected ? "Selected" : "Not Selected"}</BaseText>`}
      />
    </CustomCard>
  `;
};

Event handlers must be arrow functions:

onClick=${() => conversationHandler.sendChoice(data.id)} // correct
onClick=${conversationHandler.sendChoice(data.id)}       // incorrect

HTML template syntax cheat sheet

// HTML mode
const { html, React, Icons } = nlxai.touchpointUi;

// JSX mode
import { React, BaseText, TextButton, Icons } from "@nlxai/touchpoint-ui";

  • Use ${} for interpolation in HTML templates.

  • Nested components must be nested html templates.

  • All Touchpoint components are auto-available in HTML mode via nlxai.touchpointUi.

Complete example: Carousel of Cards

const ItemsCarousel = ({ data, conversationHandler }) => {
  const [selectedId, setSelectedId] = React.useState(null);

  return html`
    <Carousel>
      ${data.map((item) => html`
        <CustomCard
          key=${item.id}
          selected=${item.id === selectedId}
          onClick=${() => {
            setSelectedId(item.id);
            conversationHandler.sendChoice(item.id);
          }}
        >
          <CustomCardImageRow src=${item.thumbnail} alt=${item.name} />
          <CustomCardRow
            left=${html`<BaseText faded>Name</BaseText>`}
            right=${html`<BaseText>${item.name}</BaseText>`}
          />
          <CustomCardRow
            left=${html`<BaseText faded>Price</BaseText>`}
            right=${html`<BaseText>${item.price}</BaseText>`}
          />
        </CustomCard>
      `)}
    </Carousel>
  `;
};

Troubleshooting

HTML mode:

  • “nlxai is not defined”: load Touchpoint UI first and wrap in contentLoaded().

  • Components not rendering: use html and ${html...} for nested components.

  • React.useState is not a function: destructure React from nlxai.touchpointUi.

General:

  • Undefined data: check your Modality schema and log the payload.

  • Choice not sent: ensure conversationHandler.sendChoice(id) or sendSlots({ slotName: value }).

  • React version mismatch: in JSX mode import React from @nlxai/touchpoint-ui.

Component reference

Last updated