Documentation | Legion Hand Technologies

Install the Opportunities Widget as an NPM package for first-class React (and TypeScript) support.

Installation

npm install @legionhandtech/lht-react-widgets

React 17+ is a peer dependency. If your project already has React installed you're good to go.

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"
      tags="retail,food"
    />
  );
}

Props Reference

Core Props

Prop	Type	Default	Description
`baseUrl`	`string`	required	Base URL of your Legion deployment
`count`	`number`	`5`	Number of opportunities to display (1–20)
`layout`	`"horizontal" \| "vertical"`	`"horizontal"`	Layout direction
`variant`	`"portrait" \| "square" \| "banner" \| "list" \| "hero"`	auto	Card style (portrait for horizontal, list for vertical)
`tags`	`string`	—	Comma-separated list of tags to filter by
`theme`	`"light" \| "dark" \| "minimal" \| "bold" \| "corporate" \| "vibrant"`	`"light"`	Preset theme
`height`	`string`	`"auto"`	Widget height — `"auto"`, `"100%"`, or a CSS value like `"400px"`
`apiKey`	`string`	—	Optional API key for authenticated content
`className`	`string`	—	CSS class applied to the outer container
`style`	`React.CSSProperties`	—	Inline styles merged into the container
`onLoad`	`(detail) => void`	—	Called when the widget iframe finishes loading
`onError`	`(message: string) => void`	—	Called if the widget iframe fails to load

Theming Props

All theming props are optional. When omitted the widget uses its built-in defaults.

The card system keeps text off the image: the photo lives in a fixed-ratio frame and copy sits on a solid surface. The legacy overlay-panel props (oppPanelStart, oppPanelBlur, …) and shadow props were removed with the card revamp.

Card Surface

Prop	CSS Variable	Example
`oppAccent`	`--opp-accent`	`"#5a48e6"`
`oppAccentContrast`	`--opp-accent-contrast`	`"#ffffff"`
`oppCardBg`	`--opp-card-bg`	`"#ffffff"`
`oppTextColor`	`--opp-text-color`	`"#16181d"`
`oppCardRadius`	`--opp-card-radius`	`"18px"`
`oppCardShadow`	`--opp-card-shadow`	`"0 4px 12px rgba(0,0,0,.1)"`
`oppCardHoverShadow`	`--opp-card-hover-shadow`	`"0 8px 24px rgba(0,0,0,.15)"`
`oppCardBorder`	`--opp-card-border`	`"1px solid #e6e8ec"`
`oppFontFamily`	`--opp-font-family`	`"Inter, sans-serif"`

Media Frame & Chips

Prop	CSS Variable	Example
`oppMediaRatio`	`--opp-media-ratio`	`"5 / 4"`
`oppMediaBg`	`--opp-media-bg`	`"#dfe2e7"`
`oppCategoryBg`	`--opp-category-bg`	`"rgba(16,18,24,.5)"`
`oppCategoryColor`	`--opp-category-color`	`"#ffffff"`
`oppRewardBg`	`--opp-reward-bg`	`"#fdeecb"`
`oppRewardColor`	`--opp-reward-color`	`"#8a5a00"`
`oppRewardSize`	`--opp-reward-size`	`"12.5px"`

Title Typography

Prop	CSS Variable	Example
`oppTitleSize`	`--opp-title-size`	`"19px"`
`oppTitleColor`	`--opp-title-color`	`"#16181d"`
`oppTitleWeight`	`--opp-title-weight`	`"700"`
`oppTitleFontFamily`	`--opp-title-font-family`	`"Inter, sans-serif"`

Description Typography

Prop	CSS Variable	Example
`oppDescriptionSize`	`--opp-description-size`	`"13.5px"`
`oppDescriptionColor`	`--opp-description-color`	`"#626a78"`
`oppDescriptionFontFamily`	`--opp-description-font-family`	`"Inter, sans-serif"`
`oppDescriptionLineHeight`	`--opp-description-line-height`	`"1.45"`

Expires Typography

Prop	CSS Variable	Example
`oppExpiresSize`	`--opp-expires-size`	`"12.5px"`
`oppExpiresColor`	`--opp-expires-color`	`"#8b93a1"`

Buttons

Prop	CSS Variable	Example
`oppButtonRadius`	`--opp-button-radius`	`"12px"`
`oppSaveBorder`	`--opp-save-border`	`"#e0e3e8"`
`oppSaveBg`	`--opp-save-bg`	`"transparent"`
`oppSaveColor`	`--opp-save-color`	`"#626a78"`

Animation

Prop	CSS Variable	Example
`oppTransitionDuration`	`--opp-transition-duration`	`"0.3s"`

Preset Themes

Use the theme prop for quick preset styling instead of individual theming props:

Theme	Description
`light`	Default — white surface, dark accent button
`dark`	Dark card surface with light text
`minimal`	Border-only cards, no shadows
`bold`	Larger titles, rounder corners
`corporate`	Slate accent, sharp corners, no animations
`vibrant`	Indigo accent with colored hover glow

<LegionOpportunities
  baseUrl="https://your-legion-domain.com"
  theme="dark"
  count={5}
/>

Imperative Ref API

Use a React ref to call methods on the widget:

import { useRef } from "react";
import {
  LegionOpportunities,
  LegionOpportunitiesHandle,
} from "@legionhandtech/lht-react-widgets";

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

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

Available Methods

Method	Description
`refresh()`	Reloads the widget iframe

Web Component (from NPM)

If you prefer the <legion-opportunities> custom element but want to install via NPM instead of a script tag:

import "@legionhandtech/lht-react-widgets/web-component";

Then use it in your HTML or JSX:

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

TypeScript

The package ships with full TypeScript declarations. All prop interfaces are exported:

import type {
  OpportunitiesWidgetProps,
  OpportunitiesThemingProps,
  LegionOpportunitiesHandle,
} from "@legionhandtech/lht-react-widgets";

Callbacks

onLoad

Fired when the widget iframe has loaded. Receives a detail object:

<LegionOpportunities
  baseUrl="https://your-legion-domain.com"
  onLoad={(detail) => {
    console.log(detail.widget); // "opportunities"
    console.log(detail.count); // number
    console.log(detail.layout); // "horizontal" | "vertical"
    console.log(detail.tags); // string
  }}
/>

onError

Fired if the widget iframe fails to load:

<LegionOpportunities
  baseUrl="https://your-legion-domain.com"
  onError={(message) => console.error(message)}
/>

Opportunities Widget – React SDK