useNumberFormat

Provider-agnostic number formatting context for Docyrus native components. Mirror of useDateFormat, wired automatically by DocyrusTenantProvider.

Edit on GitHubEditllms.txt

iOSAndroidExpo Go

Installation

pnpm dlx @docyrus/cli add @docyrus/rn-hooks-use-number-format

The module exports useNumberFormat() (hook), <NumberFormatProvider> (provider) and isDefaultNumberFormatContext(). It has no runtime dependencies. The formatter comes from you or from a parent <DocyrusTenantProvider>.

Overview

Components call useNumberFormat() to get formatNumber(value, options?). The provider above them decides how formatting happens.

No provider mounted: the hook returns a built-in sentinel that renders String(value) ('' for null, undefined and '').
<DocyrusTenantProvider> mounted: formatNumber is backed by the tenant's numberUtils, so values follow the tenant's decimal separator, thousand separator and precision.
Custom provider mounted: wrap Intl.NumberFormat (supported on Hermes) or any other helper with <NumberFormatProvider>.

Usage

Consume in a component

import { Text } from 'react-native';

import { useNumberFormat } from '@/hooks/docyrus-native/use-number-format';

export function Total({ amount, currency }: { amount: number; currency: string }) {
  const { formatNumber } = useNumberFormat();

  return <Text>{formatNumber(amount, { variant: 'currency', currency })}</Text>;
}

Custom provider (`Intl`)

import { NumberFormatProvider } from '@/hooks/docyrus-native/use-number-format';

export function AppProviders({ children }: { children: React.ReactNode }) {
  return (
    <NumberFormatProvider
      formatNumber={(value, opts) => {
        const num = Number(value);

        if (Number.isNaN(num)) return String(value ?? '');

        const variant = opts?.variant ?? 'number';

        return new Intl.NumberFormat('en-US', {
          style: variant === 'currency' ? 'currency' : variant === 'percent' ? 'percent' : 'decimal',
          currency: opts?.currency
        }).format(num);
      }}>
      {children}
    </NumberFormatProvider>
  );
}

API Reference

`useNumberFormat()`

Takes no parameters. Returns: NumberFormatContextValue.

Field	Type	Description
`formatNumber`	`(value: unknown, options?: NumberFormatOptions) => string`	Formats a number with the active provider's strategy.

`NumberFormatOptions`

Field	Type	Description
`variant`	`'number' \| 'currency' \| 'percent'`	Output style. `DocyrusTenantProvider` treats a missing value as `'number'`; for `'percent'` it multiplies by 100 and appends `%`.
`currency`	`string`	ISO 4217 currency code, used when `variant === 'currency'`.
`decimalPrecision`	`number`	Override the fraction digits.
`thousandSeparator`	`string`	Override the thousands separator.

`<NumberFormatProvider>`

Prop	Type	Default	Description
`formatNumber`	`NumberFormatFn`	—	Required. Backs `useNumberFormat()` inside the tree.
`children`	`ReactNode`	—	Tree to wrap.

`isDefaultNumberFormatContext(ctx)`

Parameter	Type	Description
`ctx`	`NumberFormatContextValue`	A value returned by `useNumberFormat()`.

Returns: boolean. true when ctx is the no-provider sentinel rather than a real provider.

Type Exports

Type	Description
`NumberFormatFn`	`(value: unknown, options?: NumberFormatOptions) => string`.
`NumberFormatOptions`	Options accepted by `formatNumber`.
`NumberFormatContextValue`	Shape returned by `useNumberFormat()`.

useNumberFormat

On this page