Stele - Currency

Components

Currency Basic Usage Example message Props Using Currency context Playground Dates and Times Numbers Plural Select Select Ordinal

Home How Stele Works

How To

License Techdebt

Currency

Similar to numbers, how currency is formatted depends on the locale. Stele uses the browser's Intl.NumberFormat API to ensure formatting matches what users expect to see. The <Currency> component accepts as props any options you would otherwise pass to Intl.Numberformat as well as some more convenient formatting props (see below).

Basic Usage

import * as React from 'react'
import { CurrencyProvider, Currency } from '@patreon/stele'
function MyComponent(props) {
    const { myPrice } = props
    return (
        // wrap a top level component with a <CurrencyProvider> to provide
        // that currency via context to descendent components
        <CurrencyProvider value="USD">
            <Text intl>
                <p>
                    The price in the US is <Currency value={myPrice} />
                </p>
                <p>
                    {/* override currency directly via a prop */}
                    In the UK it will cost you <Currency
                        currency="GBP"
                        value={myPrice}
                    />
                </p>
                <p>
                    {/* set a new currency context with another provider */}
                    <CurrencyProvider value="EUR">
                        {/* override format for a specific locale */}
                        The price in the EU is <Currency
                            value={myPrice}
                            locale="de-DE"
                        />
                    </CurrencyProvider>
                </p>
            </Text>
        </CurrencyProvider>
    )
}

Example message

The price in the US is { myPrice, number, currency }

Props

value

Number

required

currency

Currencycode | undefined

numSubunits

Number | undefined

alwaysShowDollarName

Boolean | undefined

locale

String | undefined

truncateDecimal

Boolean | undefined

postFormatHook

Postcurrencyformatfunction | undefined

notation

Notation | undefined

compactDisplay

Compactdisplay | undefined

localeMatcher

String | undefined

style

String | undefined

currencyDisplay

String | undefined

useGrouping

Boolean | undefined

minimumIntegerDigits

Number | undefined

minimumFractionDigits

Number | undefined

maximumFractionDigits

Number | undefined

minimumSignificantDigits

Number | undefined

maximumSignificantDigits

Number | undefined

Using Currency context

import * as React from 'react'
import { CurrencyProvider, useCurrency } from '@patreon/stele'
function ParentComponent(props) {
    return (
        <CurrencyProvider value="USD">
            <ConsumingComponent />
            <WrappedComponent />
        </CurrencyProvider>
    )
}
// access the currently set currency from context with a hook
function ConsumingComponent(props) {
    const currency = useCurrency()
    return (
        <div>
            currency from context hook: {currency} {/* USD */}
        </div>
    )
}
// or access it via a higher order component
const WrappedComponent = withCurrency(function InnerComponent(props) {
    const { currency } = props
    return (
        <div>
            currency from prop: {currency} {/* USD */}
        </div>
    )
})

Playground

$0.05

Price

Currency

Locale

Truncate Decimal?

Always Show Dollar Name?

() => {
  const [currency, setCurrency] = React.useState('USD')
  const [alwaysShowDollarName, setAlwaysShowDollarName] = React.useState(
    false,
  )
  const [locale, setLocale] = React.useState('en-US')
  const [price, setPrice] = React.useState(5)
  const [truncateDecimal, setTruncateDecimal] = React.useState(false)
  return (
    <>
      {/* usage */}
      <CurrencyProvider value={currency}>
        <h3>
          <Currency
            alwaysShowDollarName={alwaysShowDollarName}
            locale={locale}
            truncateDecimal={truncateDecimal}
            value={price}
          />
        </h3>
      </CurrencyProvider>
      {/* controls */}
      <div>
        <label htmlFor="price">Price</label>
        <input
          name="price"
          value={price}
          onChange={e => setPrice(e.target.value)}
          type="number"
        />
      </div>
      <div>
        <label htmlFor="currency">Currency</label>
        <select
          name="currency"
          value={currency}
          onChange={e => setCurrency(e.target.value)}
        >
          <option value="CAD">Canadian Dollars</option>
          <option value="USD">US Dollars</option>
          <option value="GBP">UK Pounds</option>
          <option value="EUR">Euros</option>
        </select>
      </div>
      <div>
        <label htmlFor="locale">Locale</label>
        <select
          name="locale"
          value={locale}
          onChange={e => setLocale(e.target.value)}
        >
          <option value="en-US">en-US</option>
          <option value="en-CA">en-CA</option>
          <option value="de-DE">de-DE</option>
        </select>
      </div>
      <div>
        <label htmlFor="truncate">Truncate Decimal?</label>
        <input
          name="truncate"
          value={truncateDecimal}
          onChange={e => setTruncateDecimal(!truncateDecimal)}
          type="checkbox"
        />
      </div>
      <div>
        <label htmlFor="always-show-dollar-name">
          Always Show Dollar Name?
        </label>
        <input
          name="always-show-dollar-name"
          value={alwaysShowDollarName}
          onChange={e => setAlwaysShowDollarName(!alwaysShowDollarName)}
          type="checkbox"
        />
      </div>
    </>
  )
}() => {
  const [currency, setCurrency] = React.useState('USD')
  const [alwaysShowDollarName, setAlwaysShowDollarName] = React.useState(
    false,
  )
  const [locale, setLocale] = React.useState('en-US')
  const [price, setPrice] = React.useState(5)
  const [truncateDecimal, setTruncateDecimal] = React.useState(false)
  return (
    <>
      {/* usage */}
      <CurrencyProvider value={currency}>
        <h3>
          <Currency
            alwaysShowDollarName={alwaysShowDollarName}
            locale={locale}
            truncateDecimal={truncateDecimal}
            value={price}
          />
        </h3>
      </CurrencyProvider>
      {/* controls */}
      <div>
        <label htmlFor="price">Price</label>
        <input
          name="price"
          value={price}
          onChange={e => setPrice(e.target.value)}
          type="number"
        />
      </div>
      <div>
        <label htmlFor="currency">Currency</label>
        <select
          name="currency"
          value={currency}
          onChange={e => setCurrency(e.target.value)}
        >
          <option value="CAD">Canadian Dollars</option>
          <option value="USD">US Dollars</option>
          <option value="GBP">UK Pounds</option>
          <option value="EUR">Euros</option>
        </select>
      </div>
      <div>
        <label htmlFor="locale">Locale</label>
        <select
          name="locale"
          value={locale}
          onChange={e => setLocale(e.target.value)}
        >
          <option value="en-US">en-US</option>
          <option value="en-CA">en-CA</option>
          <option value="de-DE">de-DE</option>
        </select>
      </div>
      <div>
        <label htmlFor="truncate">Truncate Decimal?</label>
        <input
          name="truncate"
          value={truncateDecimal}
          onChange={e => setTruncateDecimal(!truncateDecimal)}
          type="checkbox"
        />
      </div>
      <div>
        <label htmlFor="always-show-dollar-name">
          Always Show Dollar Name?
        </label>
        <input
          name="always-show-dollar-name"
          value={alwaysShowDollarName}
          onChange={e => setAlwaysShowDollarName(!alwaysShowDollarName)}
          type="checkbox"
        />
      </div>
    </>
  )
}

Currency

.css-1r0pe6c{color:inherit;-webkit-text-decoration:none;text-decoration:none;}.css-1r0pe6c:hover{-webkit-text-decoration:underline;text-decoration:underline;}Basic Usage

Example message

Props

Using Currency context

Playground

$0.05

Basic Usage