React components

Theming

Fin's blocks look like near.com until you restyle them. Four levels restyle them, from a few variables to entirely your own markup. Use the lightest that does what you need; they combine.

LevelYou changeUse it for
Variables--fin-* custom propertiesPalette, typeface, corners and density, everywhere at once
ClassesclassName and classNamesOne block, or one of its parts, in one place
AttributesCSS on data-fin-part and data-fin-uiA part or a primitive (every button, badge, notice) in every block
Your own markupThe view models in @nearai/financial-agents-react/modelA block drawn entirely by your components

How the stylesheet stays out of your way

@nearai/financial-agents-react/styles.css styles nothing outside Fin's blocks:

  • Every element rule sits in the fin cascade layer, so your unlayered CSS always wins.
  • Every class is prefixed fin: and every variable --fin-, so nothing collides with your classes or theme, Tailwind's included.
  • Its small reset applies only to Fin's elements. Pages without Tailwind render the blocks correctly; pages with it see no change.
  • What any Tailwind 4 build shares sits outside the layer: the --tw-* and --twsa-* properties registered with @property, and the spin, ping, pulse and enter keyframes. Rename your own keyframes if they use those names.

In a Tailwind app, declare the layer order once, above your Tailwind import:

app/globals.css
@layer theme, base, fin, components, utilities;
@import "tailwindcss";

1. Variables

Set --fin-* variables on :root, or on any element above Fin's blocks. This makes them look like another product: an indigo accent, warm greys, a serif face, square corners and a denser rhythm.

fin-theme.css
:root {
  --fin-font-sans: Georgia, "Times New Roman", serif;
  --fin-color-green-500: oklch(0.831 0.12 277);
  --fin-color-green-600: oklch(0.711 0.16 277);
  --fin-color-green-700: oklch(0.5935 0.2 277);
  --fin-color-gray-500: oklch(0.556 0.011 70);
  --fin-color-gray-900: oklch(0.205 0.006 70);
  --fin-radius-md: 0px;
  --fin-radius-lg: 0px;
  --fin-radius-xl: 0px;
  --fin-spacing: 0.2rem;
}
VariablesStepsDrives
--fin-color-green-<step>50, 100, 200 … 900, 950The accent: primary buttons, success, rising figures, the agent's mark
--fin-color-red-<step>50, 100, 200 … 900, 950Danger and falling figures
--fin-color-yellow-<step>50, 100, 200 … 900, 950Caution: pending approvals and holds
--fin-color-gray-<step>10, 25, 50, 100, 150, 200, 300 … 800, 850, 875, 900, 950Surfaces, borders and ink
--fin-color-blue-<step>300, 500, 700Information
--fin-color-whiteText on a filled accent
--fin-font-sans, --fin-font-monoTypefaces. Fin loads no fonts of its own
--fin-font-weight-<weight>normal, medium, semibold, boldWeights
--fin-text-<size>, --fin-text-<size>--line-heightxs, sm, base, lg, xl, 2xl, 3xl, 4xlThe type scale
--fin-leading-<name>, --fin-tracking-<name>tight, snug, normal; tight, wideLine height and letter spacing
--fin-radius-<size>sm, md, lg, xl, 2xl, 3xlCorners
--fin-spacingThe base of every padding, margin and gap
--fin-container-<size>sm, md, lg, xl, 3xl, 4xlThe widths some cards stop growing at
--fin-ease-<curve>out, in-outEasing curves
--fin-default-transition-<setting>duration, timing-functionThe default transition
--fin-animate-<name>spin, pulse, pingSpinners and live dots

Dark mode

Blocks draw dark inside an element with the dark class (near.com's and next-themes' class strategy), or inside data-fin-theme="dark". .not-dark or data-fin-theme="light" keeps a subtree light. Scope variables to one theme:

CSS
.dark,
[data-fin-theme="dark"] {
  --fin-color-gray-900: oklch(0.96 0.004 70);
}

2. Classes

Every block takes className for its root. A block with named parts also takes classNames, one class per part:

branded-approval.tsx
import { ApprovalCard, type ApprovalCardProps } from "@nearai/financial-agents-react";

export function BrandedApproval(props: ApprovalCardProps) {
  return (
    <ApprovalCard
      {...props}
      className="my-card"
      classNames={{ band: "my-card-band", actions: "my-card-actions" }}
    />
  );
}

Your classes come after Fin's and your CSS sits outside its layer, so yours win. Each block's parts are in the components reference.

3. Attributes

Two attributes are the stable hooks for CSS that reaches into a block. Fin's own class names are not: they can change in any release.

data-fin-part

Names every block and part: approval-card on an approval card, approval-card-evidence on its exact terms. Target a part everywhere it appears:

CSS
[data-fin-part="approval-card-evidence"] {
  display: none;
}
Root data-fin-partBlock
activity-groupActivityGroup
approval-cardApprovalCard. Inside: decision-countdown, the time left to decide; execution-swaps, a multi-swap execution's swaps; grid-band, a grid approval's band
asset-iconAssetIcon
asset-linkA token in a card or a ticker in a reply, linked to your page for it by routes.asset
automation-cardAutomationCard
comparison-cardComparisonCard. Inside: sparkline, each asset's trend line
contacts-cardContactsCard
contract-termsContractTerms
memecoins-cardMemecoinsCard
grid-bandGridBand, also inside a grid's ApprovalCard and GridCard
grid-cardGridCard
message-markdownMessageMarkdown. Inside: sparkline, a bolded asset's trend line
mint-addressA Solana token's address, shortened, with its copy button, where a Solana card shows one to tell look-alikes apart: in TokenCandidatesCard, MemecoinsCard, SolanaTokenCard and SolanaHoldingsCard
next-stepsNextSteps
orders-cardOrdersCard
perps-firing-cardPerpsFiringCard
holdings-cardHoldingsCard
pending-approval-chipPendingApprovalChip
prediction-market-cardPredictionMarketCard
prediction-preview-cardPredictionPreviewCard
predictions-cardPredictionsCard
price-cardPriceCard
question-cardQuestionCard
run-footerRunFooter
run-progressRunProgress
run-receiptRunReceipt
settlement-receiptSettlementReceipt
solana-holdings-cardSolanaHoldingsCard
solana-receiptSolanaReceipt
solana-token-cardSolanaTokenCard
token-candidates-cardTokenCandidatesCard
tool-call-cardToolCallCard
vaults-cardVaultsCard
wallet-cardWalletCard

data-fin-ui

Names every primitive a block draws with: each button, badge, notice and line of text. Where it applies, a primitive also carries data-fin-variant, data-fin-size, data-fin-tone and data-fin-state, so one rule restyles it in every block:

CSS
[data-fin-ui="button"] {
  border-radius: 9999px;
}
[data-fin-ui="button"][data-fin-variant="primary"] {
  background: #312e81;
  color: #ffffff;
}
[data-fin-ui="badge"] {
  border-radius: 2px;
  letter-spacing: 0.06em;
  text-transform: uppercase;
}
data-fin-uiIsCarries
buttonA buttonvariant: primary, accent, secondary, outline, dark, light, transparent, destructive, destructive-soft, success-soft; size: xs, sm, md, lg, xl
icon-buttonAn icon-only button, such as a notice's dismiss or a reply's thumbsvariant, size
badgeA status labeltone: neutral, accent, caution, danger, info; variant: outline, soft, solid; size: sm, md
noticeA message under a card, such as a refusaltone: info, accent, caution, danger
textA line of textvariant: display, title, heading, subheading, body, body-sm, label, caption, mono, muted; tone: default, soft, muted, faint, accent, caution, danger
proseA reply's textsize: sm, md
stream-caretThe caret after live text
cardA paneltone: raised, flat, inset, caution, danger, accent
disclosureA section that opens in placesize: sm, md
dialogA dialogvariant: modal, drawer, page, sheet; size: sm, md, lg; tone: neutral, danger
spinnerWork in progresssize: xs, sm, md
kbdA key cap, such as a question card's number keys
segmented-controlA radio group drawn as one control, such as a price card's range tabssize: sm, md
tool-indicatorA tool call's status glyphstate: running, completed, failed, denied, invalid_input, pending_approval, pending_input, pending_confirmation, refunded, partial, not_executed
json-viewAn exact input or result, as JSON
token-iconA token's disc
network-badgeA token's network badge

The Themes/Parts stories show both attributes at work.

4. Your own markup

@nearai/financial-agents-react/model holds the logic behind every block, so your components can draw Fin's data with none of its markup or styles. approvalContent reads an approval as the card does:

plain-approval.tsx
import { type ApprovalView, approvalContent } from "@nearai/financial-agents-react/model";

export function PlainApproval(props: { approval: ApprovalView; onDecide: (ok: boolean) => void }) {
  const content = approvalContent(props.approval);
  return (
    <article aria-label={content.headline}>
      <h3>{content.headline}</h3>
      <dl>
        {content.terms.map((term) => (
          <div key={term.label}>
            <dt>{term.label}</dt>
            <dd>{term.value}</dd>
          </div>
        ))}
      </dl>
      {content.readable ? null : <p>Update the app to review this request.</p>}
      <button type="button" onClick={() => props.onDecide(false)}>
        Cancel
      </button>
      {content.readable ? (
        <button type="button" onClick={() => props.onDecide(true)}>
          {content.approveLabel}
        </button>
      ) : null}
    </article>
  );
}

The view models cover the thread, replies, activity, automations, amounts and tokens the same way.

Fin documentation Built from the API contract · v1

Search all documentation