@get-asset/sdk

ExpensesCard

Headless compound for the period's expenses and the change versus the prior period. A decrease reads as a positive tone; an increase as negative. Period defaults to the AssetProvider's year/month.

Anatomy

Import the primitive and compose the parts you need.

<ExpensesCard.Root year={2026}>
  <ExpensesCard.Loading>…</ExpensesCard.Loading>
  <ExpensesCard.Error>
    <ExpensesCard.ErrorMessage />
    <ExpensesCard.Retry />
  </ExpensesCard.Error>
  <ExpensesCard.Success>
    <ExpensesCard.Period />
    <ExpensesCard.Expenses />
    <ExpensesCard.Change />
    <ExpensesCard.Tone>{/* data-tone="positive" */}</ExpensesCard.Tone>
  </ExpensesCard.Success>
</ExpensesCard.Root>

Required scopes

The access token used by AssetProvider must include this scope for this primitive to fetch data successfully:

report:read

API reference

Root props

Prop	Type	Default	Description
`year`	`number`	—	Fiscal year to report on. Falls back to the AssetProvider's year.
`month`	`number \| null`	—	Month (1-12). When set the card shows that month vs. the previous month; null explicitly forces a whole-year range. Falls back to the AssetProvider's month (default: no month).
`expenses`	`number`	—	Override fetched expenses total (positive number). Skips the API call.
`previousExpenses`	`number`	—	Override fetched prior-period expenses.
`state`	`"loading" \| "error"`	—	Force a specific state for testing.
`locked`	`boolean`	—	Gate the report for an unentitled viewer. Activates the Locked state and skips the API fetch. See /docs/sdk/locked-upsell.
`upsell`	`{ title?, description?, ctaLabel?, onUpgrade? }`	—	Locked-state copy + upgrade handler; merged field-by-field over the card's default copy, then the generic fallback.
`children`required	`ReactNode`	—	Compound parts.

Parts

Container

Always rendered. Provides data and context to its children.

Part	Description
`ExpensesCard.Root`	Fetches the current and previous period P&L and provides context.

Success

Renders children when expenses data is available.

Part	Description
`ExpensesCard.Success`	State wrapper. Compose the value UI inside.
`ExpensesCard.Period` `asChild?`	Renders the resolved period — defaults to MMM YYYY or YYYY. Pass format(year, month) to override.
`ExpensesCard.Expenses` `asChild?`	Renders the current-period expenses total.
`ExpensesCard.Change` `asChild?`	Renders the period-over-period percent change.
`ExpensesCard.Tone` `asChild?`	Wrapper that adds data-tone="positive" \| "negative" \| "neutral" to its child. Tone is inverted vs. Revenue — a drop in expenses is "positive".

Loading

Renders children only while the fetch is in flight.

Part	Description
`ExpensesCard.Loading`	State wrapper. Render any skeleton or placeholder UI inside.

Error

Renders children when the fetch fails.

Part	Description
`ExpensesCard.Error`	State wrapper. Compose the error UI inside.
`ExpensesCard.ErrorMessage` `asChild?`	Renders the error's message string.
`ExpensesCard.Retry` `asChild?`	Button that re-runs the fetch on click.

Locked

Renders when `locked` is set — the viewer isn't entitled to the report. Mutually exclusive with the other states, and no data is fetched. See the Locked / upsell guide for composing the teaser + upgrade UI.

Part	Description
`ExpensesCard.Locked`	State wrapper. Compose the upgrade / upsell UI inside — see LockedUpsell.

Unlocked

Renders whenever the card is NOT locked — the inverse of Locked.

Part	Description
`ExpensesCard.Unlocked`	State wrapper. Renders children whenever the card isn't locked.

Hooks

Part	Description
`useExpensesCard()`	Hook returning the full context value (year, expenses, previousExpenses, percentChange, tone, loading, error, locked, retry).