Money

A negative balance means different things in different places. On an expense report it is a loss; on a tenant’s account it is money the tenant has paid ahead. credit says which, so the same number is not painted as a debt where it is good news.

Preview

Show code Copy

Debts, credits and zero

Rent due Paid in advance Arrears written off Deposit held

Show code Copy

Amount	Reads as	Colour
Positive	KES 28,000.00	Text
Negative	−KES 1,200.00, or (KES 1,200.00) with negative="parentheses"	Danger
Negative, with credit	KES 5,000.00 CR	Success
Zero	KES 0.00	Muted
Empty	—	Text

The minus sign is a true minus, not a hyphen, so it lines up with the figures in a column. A screen reader hears “minus” or “in credit” rather than the punctuation. plain keeps the colour off when the column is already coloured by something else.

Columns

Tabular figures are always on, so digits are all one width. align="end" makes the figure a block lined up to the right, which is what a column of amounts needs.

Scale and precision

scale="compact" shortens 1,250,000 to 1.3M for a card or a cell, and keeps the full figure in the tooltip. Decimals follow the currency — two for shillings, none for yen — unless precision says otherwise. Payment APIs that send cents can pass them as they are with minor.

Drilling in

An amount is usually a sum of something. href makes it a link to the ledger that adds up to it; drillable makes it a button that fires nana-drill, for an app that opens the breakdown in place.

Show code Copy

Installation

npm install @nana-tec/ui-components

Or copy the source in and own it:

npx @nana-tec/ui add money

Usage

import "@nana-tec/ui-components/money";

<nana-money amount="28500" currency="KES"></nana-money>
<nana-money amount="-1200" currency="KES" credit></nana-money>
<nana-money amount="1250000" currency="KES" scale="compact" href="/ledger"></nana-money>

const el = document.querySelector("nana-money");
el.addEventListener("nana-drill", (e) => console.log(e.detail));

API

Properties

Property	Attribute	Type	Default	Description
align	align	MoneyAlign | undefined	—	Take the full width and line the figure up to one side, as a table column does
amount	amount	number | null	null	The amount, in major units unless minor is set; empty shows a dash
credit	credit	boolean	false	Read a negative amount as money held in credit rather than owed
currency	currency	string	'KES'	ISO 4217 code
display	display	MoneyCurrencyDisplay	'code'	Show the currency as its code, its symbol, or not at all
drillable	drillable	boolean	false	Offer the amount as a button that fires nana-drill, when there is no page to link to
href	href	string	''	Link to what makes up the amount — the ledger, the invoice
locale	locale	string	''	BCP 47 locale for the digits and separators; the reader's own when empty
minor	minor	boolean	false	amount is in minor units — cents — as most payment APIs send it
negative	negative	MoneyNegative	'minus'	How a debt is written
plain	plain	boolean	false	Leave debts and credits in the text colour
precision	precision	number | undefined	—	Decimal places, when the currency's own will not do
scale	scale	MoneyScale	'full'	compact shortens large figures to 1.3M and keeps the full one in the tooltip
size	size	MoneySize	'md'

Events

Event	Description
nana-drill	The reader asked to see what makes up the amount (detail.amount, detail.currency)

CSS parts

Part	Description
::part(base)	The figure, or the link or button wrapping it
::part(amount)	The written amount

CSS custom properties

Property	Description
--nana-money-negative	Colour of a debt
--nana-money-credit	Colour of a credit
--nana-money-zero	Colour of a zero amount

Storybook

Explore Money interactively Every state, prop, and edge case — with live controls — in Storybook.

View in Storybook