@get-asset/sdk

OperatingExpensesCard

Headless compound surfacing the top Nexpense categories for a period, each with a proportional bar. Categories come from P&L report leaf records under the operating-expenses group. Period defaults to the AssetProvider's year/month.

Anatomy

Import the primitive and compose the parts you need.

<OperatingExpensesCard.Root year={2026} limit={5}>
  <OperatingExpensesCard.Success>
    <OperatingExpensesCard.Period />
    <OperatingExpensesCard.Total />
    <OperatingExpensesCard.Categories>
      <OperatingExpensesCard.CategoryName />
      <OperatingExpensesCard.CategoryAmount />
      <OperatingExpensesCard.CategoryBar />
    </OperatingExpensesCard.Categories>
  </OperatingExpensesCard.Success>
</OperatingExpensesCard.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. Falls back to the AssetProvider's year.
`month`	`number \| null`	—	Month (1-12). When set the card scopes categories to that single month; null explicitly forces a whole-year range. Falls back to the AssetProvider's month (default: no month).
`limit`	`number`	`5`	Maximum categories to display.
`categories`	`OperatingExpenseCategoryOverride[]`	—	Override fetched data. Each entry: { name, amount }.
`scale`	`number`	—	Override the bar chart maximum.
`state`	`"loading" \| "error" \| "empty"`	—	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
`OperatingExpensesCard.Root`	Fetches the P&L report, extracts expense leaves, and provides context.

Success

Renders when categories are available.

Part	Description
`OperatingExpensesCard.Success`	State wrapper. Compose the category list inside.
`OperatingExpensesCard.Period` `asChild?`	Renders the resolved period — defaults to MMM YYYY or YYYY. Pass format(year, month) to override.
`OperatingExpensesCard.Total` `asChild?`	Sum of the categories displayed.
`OperatingExpensesCard.Categories`	Iterates children once per category, up to limit.
`OperatingExpensesCard.CategoryName` `asChild?`	Name of the current category.
`OperatingExpensesCard.CategoryAmount` `asChild?`	Amount of the current category.
`OperatingExpensesCard.CategoryBar` `style?, className?`	Bar sized by amount / scale.

Loading

Renders while the fetch is in flight.

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

Empty

Renders when there are no expense categories.

Part	Description
`OperatingExpensesCard.Empty`	State wrapper. Render an empty-state message inside.

Error

Renders on fetch error.

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

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
`OperatingExpensesCard.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
`OperatingExpensesCard.Unlocked`	State wrapper. Useful for gating extras (like the insights panel) that should also disappear while locked.

Hooks

Part	Description
`useOperatingExpensesCard()`	Hook returning categories, total, scale, loading, error, locked, retry.
`useOperatingExpenseCategory()`	Hook for components inside a Categories iteration.