@legionhandtech/lht-react-widgets

Embeddable Legion widgets for React applications. Each widget renders in an isolated iframe — no style conflicts, no CORS issues, no extra dependencies.

Install

npm install @legionhandtech/lht-react-widgets

React 17+ is a peer dependency (only needed for the React components — web component imports work without React).

Quick Start

import { LegionOpportunities } from '@legionhandtech/lht-react-widgets';

function App() {
  return (
    <LegionOpportunities
      baseUrl="https://your-legion-domain.com"
      count={5}
      layout="horizontal"
      theme="light"
    />
  );
}

Widgets

LegionOpportunities

Displays opportunity cards in a horizontal or vertical layout.

import { LegionOpportunities } from '@legionhandtech/lht-react-widgets';

<LegionOpportunities
  baseUrl="https://your-legion-domain.com"
  count={5}
  layout="horizontal"
  theme="dark"
  tags="featured,new"
  height="400px"
  apiKey="your-api-key"
  onLoad={(detail) => console.log('Loaded', detail)}
  onError={(msg) => console.error(msg)}
/>

| Prop | Type | Default | Description | |------|------|---------|-------------| | baseUrl | string | required | Base URL of your Legion instance | | count | number | 5 | Number of opportunities (1–20) | | layout | "horizontal" \| "vertical" | "horizontal" | Card layout direction | | tags | string | — | Comma-separated tag filter | | theme | "light" \| "dark" \| "minimal" \| "bold" \| "corporate" \| "vibrant" | "light" | Preset theme | | height | string | "auto" | Widget height CSS value | | apiKey | string | — | API key for authentication |

LegionCommunityGallery

A media gallery showcasing community content.

import { LegionCommunityGallery } from '@legionhandtech/lht-react-widgets';

<LegionCommunityGallery
  baseUrl="https://your-legion-domain.com"
  count={4}
  theme="light"
  communityUrl="/community"
/>

| Prop | Type | Default | Description | |------|------|---------|-------------| | baseUrl | string | required | Base URL of your Legion instance | | count | number | 4 | Number of gallery items (1–12) | | theme | "light" \| "dark" | "light" | Preset theme | | showViewAll | boolean | true | Show "View all" link | | viewAllUrl | string | "/gallery" | URL for the "View all" link | | communityUrl | string | — | URL when clicking a media item | | height | string | "auto" | Widget height CSS value |

LegionQA

An interactive Q&A / knowledge-base widget.

import { LegionQA } from '@legionhandtech/lht-react-widgets';

<LegionQA
  baseUrl="https://your-legion-domain.com"
  authToken="jwt-token"
  productId="prod-123"
  theme="light"
/>

| Prop | Type | Default | Description | |------|------|---------|-------------| | baseUrl | string | required | Base URL of your Legion instance | | authToken | string | — | JWT token for authenticated features | | productId | string | — | Scope questions to a product | | username | string | "Anonymous" | Display name | | pageSize | number | 5 | Items per page | | theme | "light" \| "dark" | "light" | Preset theme | | showSearch | boolean | true | Show search bar | | showAskButton | boolean | true | Show "Ask a Question" button | | width | string | "600px" | Widget width CSS value | | height | string | "800px" | Widget height CSS value |

LegionSocial

A social feed widget with grid and feed layouts.

import { LegionSocial } from '@legionhandtech/lht-react-widgets';

<LegionSocial
  baseUrl="https://your-legion-domain.com"
  layout="feed"
  theme="dark"
  channel="general"
/>

| Prop | Type | Default | Description | |------|------|---------|-------------| | baseUrl | string | required | Base URL of your Legion instance | | layout | "feed" \| "grid" \| "compact" | "feed" | Layout style | | theme | "light" \| "dark" | "light" | Preset theme | | rows | number | 3 | Number of rows (grid layout) | | cols | number | 3 | Number of columns (grid layout) | | communityUrl | string | — | Link to full community page | | channel | string | — | Filter to a specific channel | | authToken | string | — | JWT token | | userId | string | — | Current user ID | | username | string | — | Current user display name | | height | string | "800" | Widget height CSS value |

LegionWallet

Displays a user's wallet balance and transaction history.

import { LegionWallet } from '@legionhandtech/lht-react-widgets';

<LegionWallet
  baseUrl="https://your-legion-domain.com"
  userId="user-123"
  apiKey="your-api-key"
  theme="light"
/>

| Prop | Type | Default | Description | |------|------|---------|-------------| | baseUrl | string | required | Base URL of your Legion instance | | userId | string | — | User ID to display wallet for | | apiKey | string | — | API key for authentication | | theme | "light" \| "dark" | "light" | Preset theme | | showBalance | boolean | — | Show the balance section | | showHistory | boolean | — | Show the transaction history | | height | string | "500px" | Widget height CSS value |

LegionMatrix

A matrix / leaderboard display widget.

import { LegionMatrix } from '@legionhandtech/lht-react-widgets';

<LegionMatrix
  baseUrl="https://your-legion-domain.com"
  theme="dark"
  emptyTitle="No data yet"
  height="600px"
/>

| Prop | Type | Default | Description | |------|------|---------|-------------| | baseUrl | string | required | Base URL of your Legion instance | | theme | "light" \| "dark" | "light" | Preset theme | | emptyTitle | string | — | Title shown when no data | | emptyIcon | string | — | Icon shown when no data | | height | string | "600px" | Widget height CSS value |

Common Props

Every widget also accepts:

| Prop | Type | Description | |------|------|-------------| | className | string | CSS class on the wrapper <div> | | style | React.CSSProperties | Inline styles on the wrapper <div> | | onLoad | (detail) => void | Fires when the widget iframe loads | | onError | (message: string) => void | Fires when the widget iframe fails to load |

Theming

Each widget supports fine-grained CSS-variable theming via additional props. Pass them alongside the core props:

<LegionOpportunities
  baseUrl="https://your-legion-domain.com"
  oppTitleColor="#1a1b1e"
  oppButtonBg="#228be6"
  oppCardRadius="16px"
  oppTransitionDuration="0.2s"
/>

Theming props are prefixed by widget name (opp*, gallery*, qa*, social*, wallet*, matrix*). Full lists are available in each widget's TypeScript types:

import type {
  OpportunitiesThemingProps,
  CommunityGalleryThemingProps,
  QAThemingProps,
  SocialThemingProps,
  WalletThemingProps,
  MatrixThemingProps,
} from '@legionhandtech/lht-react-widgets';

Imperative Ref

All widgets expose a refresh() method via React ref:

import { useRef } from 'react';
import { LegionOpportunities } from '@legionhandtech/lht-react-widgets';
import type { LegionOpportunitiesHandle } from '@legionhandtech/lht-react-widgets';

function App() {
  const ref = useRef<LegionOpportunitiesHandle>(null);

  return (
    <>
      <button onClick={() => ref.current?.refresh()}>Reload</button>
      <LegionOpportunities ref={ref} baseUrl="https://your-legion-domain.com" />
    </>
  );
}

Handle types: LegionOpportunitiesHandle, LegionCommunityGalleryHandle, LegionQAHandle, LegionSocialHandle, LegionWalletHandle, LegionMatrixHandle.

Web Components (from NPM)

If you prefer custom elements over React components, import the web component entry:

// Register <legion-opportunities> custom element
import '@legionhandtech/lht-react-widgets/web-component';

Then use it in HTML or JSX:

<legion-opportunities
  base-url="https://your-legion-domain.com"
  count="5"
  layout="horizontal"
  theme="light">
</legion-opportunities>

Available web component imports:

| Import Path | Custom Element | |-------------|---------------| | /web-component | <legion-opportunities> | | /community-gallery-web-component | <legion-community-gallery> | | /qa-web-component | <legion-qa> | | /social-web-component | <legion-social> | | /wallet-web-component | <legion-wallet> | | /matrix-web-component | <legion-matrix> |

Web component imports do not require React.

Sub-path Imports

For smaller bundles, import only the widget you need:

import { LegionOpportunities } from '@legionhandtech/lht-react-widgets/opportunities';
import { LegionCommunityGallery } from '@legionhandtech/lht-react-widgets/community-gallery';
import { LegionQA } from '@legionhandtech/lht-react-widgets/qa';
import { LegionSocial } from '@legionhandtech/lht-react-widgets/social';
import { LegionWallet } from '@legionhandtech/lht-react-widgets/wallet';
import { LegionMatrix } from '@legionhandtech/lht-react-widgets/matrix';

TypeScript

The package ships with full TypeScript declarations (.d.ts and .d.mts). All prop interfaces, theming types, and ref handle types are exported.

License

MIT