Formatting Pattern | Bootspring Docs

Format numbers, currency, text, and file sizes consistently across your application.

Overview#

Consistent formatting improves user experience and reduces code duplication. This pattern provides utilities for numbers, currency, text manipulation, and duration formatting using native JavaScript APIs and custom helpers.

When to use:

Displaying prices and currency
Formatting large numbers (1K, 1M)
Text truncation and highlighting
File size display
Duration and time formatting

Key features:

Number formatting with locales
Currency handling
Text manipulation
File size formatting
Duration display
React components

Code Example#

Number Formatting#

// lib/format/numbers.ts

// Format number with locale
export function formatNumber(
  value: number,
  options?: Intl.NumberFormatOptions
): string {
  return new Intl.NumberFormat('en-US', options).format(value)
}

// Compact number (1K, 1M, etc.)
export function formatCompact(value: number): string {
  return new Intl.NumberFormat('en-US', {
    notation: 'compact',
    maximumFractionDigits: 1
  }).format(value)
}

// Percentage
export function formatPercent(value: number, decimals = 1): string {
  return new Intl.NumberFormat('en-US', {
    style: 'percent',
    minimumFractionDigits: decimals,
    maximumFractionDigits: decimals
  }).format(value)
}

// Ordinal (1st, 2nd, 3rd, etc.)
export function formatOrdinal(value: number): string {
  const pr = new Intl.PluralRules('en-US', { type: 'ordinal' })
  const suffixes: Record<string, string> = {
    one: 'st',
    two: 'nd',
    few: 'rd',
    other: 'th'
  }
  return `${value}${suffixes[pr.select(value)]}`
}

// Decimal places
export function formatDecimal(value: number, places = 2): string {
  return value.toFixed(places)
}

// With units
export function formatWithUnit(
  value: number,
  unit: string,
  options?: { compact?: boolean }
): string {
  const formatted = options?.compact ? formatCompact(value) : formatNumber(value)
  return `${formatted} ${unit}${value !== 1 ? 's' : ''}`
}

Currency Formatting#

// lib/format/currency.ts

interface CurrencyOptions {
  currency?: string
  locale?: string
  compact?: boolean
}

export function formatCurrency(
  amount: number,
  options: CurrencyOptions = {}
): string {
  const { currency = 'USD', locale = 'en-US', compact = false } = options

  return new Intl.NumberFormat(locale, {
    style: 'currency',
    currency,
    notation: compact ? 'compact' : 'standard',
    maximumFractionDigits: compact ? 1 : 2
  }).format(amount)
}

// Format cents to dollars
export function formatCents(cents: number, options?: CurrencyOptions): string {
  return formatCurrency(cents / 100, options)
}

// Parse currency string to number
export function parseCurrency(value: string): number {
  const cleaned = value.replace(/[^0-9.-]+/g, '')
  return parseFloat(cleaned) || 0
}

// Currency input formatter (for controlled inputs)
export function formatCurrencyInput(value: string): string {
  const num = value.replace(/[^0-9]/g, '')
  if (!num) return ''
  const cents = parseInt(num, 10)
  return formatCents(cents)
}

Text Formatting#

// lib/format/text.ts

// Truncate with ellipsis
export function truncate(text: string, maxLength: number): string {
  if (text.length <= maxLength) return text
  return text.slice(0, maxLength - 3) + '...'
}

// Truncate by words
export function truncateWords(text: string, maxWords: number): string {
  const words = text.split(/\s+/)
  if (words.length <= maxWords) return text
  return words.slice(0, maxWords).join(' ') + '...'
}

// Capitalize first letter
export function capitalize(text: string): string {
  return text.charAt(0).toUpperCase() + text.slice(1).toLowerCase()
}

// Title case
export function titleCase(text: string): string {
  return text
    .toLowerCase()
    .split(' ')
    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
    .join(' ')
}

// Sentence case
export function sentenceCase(text: string): string {
  return text.charAt(0).toUpperCase() + text.slice(1).toLowerCase()
}

// Slugify
export function slugify(text: string): string {
  return text
    .toLowerCase()
    .trim()
    .replace(/[^\w\s-]/g, '')
    .replace(/[\s_-]+/g, '-')
    .replace(/^-+|-+$/g, '')
}

// Pluralize
export function pluralize(
  count: number,
  singular: string,
  plural?: string
): string {
  if (count === 1) return singular
  return plural ?? `${singular}s`
}

// Add "a" or "an"
export function addArticle(word: string): string {
  const vowels = ['a', 'e', 'i', 'o', 'u']
  const article = vowels.includes(word[0].toLowerCase()) ? 'an' : 'a'
  return `${article} ${word}`
}

Text Highlighting#

// lib/format/text.ts

interface HighlightPart {
  text: string
  highlighted: boolean
}

export function highlightText(
  text: string,
  query: string
): HighlightPart[] {
  if (!query) return [{ text, highlighted: false }]

  const regex = new RegExp(`(${escapeRegex(query)})`, 'gi')
  const parts = text.split(regex)

  return parts.map(part => ({
    text: part,
    highlighted: part.toLowerCase() === query.toLowerCase()
  }))
}

function escapeRegex(str: string): string {
  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
}

// React component
export function Highlight({ text, query }: { text: string; query: string }) {
  const parts = highlightText(text, query)

  return (
    <>
      {parts.map((part, i) => (
        <span
          key={i}
          className={part.highlighted ? 'bg-yellow-200' : undefined}
        >
          {part.text}
        </span>
      ))}
    </>
  )
}

File Size Formatting#

// lib/format/filesize.ts

const units = ['B', 'KB', 'MB', 'GB', 'TB', 'PB']

export function formatFileSize(bytes: number, decimals = 2): string {
  if (bytes === 0) return '0 B'

  const k = 1024
  const i = Math.floor(Math.log(bytes) / Math.log(k))
  const size = bytes / Math.pow(k, i)

  return `${size.toFixed(decimals)} ${units[i]}`
}

export function parseFileSize(sizeString: string): number {
  const match = sizeString.match(/^([\d.]+)\s*([A-Z]+)$/i)
  if (!match) return 0

  const [, value, unit] = match
  const unitIndex = units.findIndex(u => u.toLowerCase() === unit.toLowerCase())
  if (unitIndex === -1) return 0

  return parseFloat(value) * Math.pow(1024, unitIndex)
}

Duration Formatting#

// lib/format/duration.ts

interface DurationParts {
  days: number
  hours: number
  minutes: number
  seconds: number
}

export function parseDuration(ms: number): DurationParts {
  const seconds = Math.floor(ms / 1000) % 60
  const minutes = Math.floor(ms / (1000 * 60)) % 60
  const hours = Math.floor(ms / (1000 * 60 * 60)) % 24
  const days = Math.floor(ms / (1000 * 60 * 60 * 24))

  return { days, hours, minutes, seconds }
}

export function formatDuration(
  ms: number,
  options?: { short?: boolean }
): string {
  const { days, hours, minutes, seconds } = parseDuration(ms)
  const parts: string[] = []

  if (options?.short) {
    if (days > 0) parts.push(`${days}d`)
    if (hours > 0) parts.push(`${hours}h`)
    if (minutes > 0) parts.push(`${minutes}m`)
    if (seconds > 0 || parts.length === 0) parts.push(`${seconds}s`)
    return parts.join(' ')
  }

  if (days > 0) parts.push(`${days} day${days !== 1 ? 's' : ''}`)
  if (hours > 0) parts.push(`${hours} hour${hours !== 1 ? 's' : ''}`)
  if (minutes > 0) parts.push(`${minutes} minute${minutes !== 1 ? 's' : ''}`)
  if (seconds > 0 || parts.length === 0) {
    parts.push(`${seconds} second${seconds !== 1 ? 's' : ''}`)
  }

  return parts.join(', ')
}

// Timer format (HH:MM:SS)
export function formatTimer(ms: number): string {
  const { hours, minutes, seconds } = parseDuration(ms)
  const pad = (n: number) => n.toString().padStart(2, '0')

  if (hours > 0) {
    return `${pad(hours)}:${pad(minutes)}:${pad(seconds)}`
  }
  return `${pad(minutes)}:${pad(seconds)}`
}

// Video duration format
export function formatVideoDuration(seconds: number): string {
  const mins = Math.floor(seconds / 60)
  const secs = Math.floor(seconds % 60)
  return `${mins}:${secs.toString().padStart(2, '0')}`
}

React Components#

// components/format/Currency.tsx
import { formatCurrency } from '@/lib/format/currency'

interface CurrencyProps {
  value: number
  currency?: string
  compact?: boolean
}

export function Currency({
  value,
  currency = 'USD',
  compact = false
}: CurrencyProps) {
  return <span>{formatCurrency(value, { currency, compact })}</span>
}

// components/format/Number.tsx
import { formatNumber, formatCompact, formatPercent } from '@/lib/format/numbers'

interface NumberProps {
  value: number
  compact?: boolean
  percent?: boolean
}

export function Number({ value, compact, percent }: NumberProps) {
  if (percent) return <span>{formatPercent(value)}</span>
  if (compact) return <span>{formatCompact(value)}</span>
  return <span>{formatNumber(value)}</span>
}

// components/format/FileSize.tsx
import { formatFileSize } from '@/lib/format/filesize'

interface FileSizeProps {
  bytes: number
  decimals?: number
}

export function FileSize({ bytes, decimals = 2 }: FileSizeProps) {
  return <span>{formatFileSize(bytes, decimals)}</span>
}

Usage Instructions#

Create format utilities: Add functions to lib/format/ directory
Use consistently: Import formatters across your codebase
Consider locale: Use Intl APIs for locale-aware formatting
Create React components: Wrap formatters in reusable components
Handle edge cases: Check for null, undefined, and invalid values

Best Practices#

Use Intl APIs - Native browser support for i18n formatting
Be consistent - Use the same format everywhere
Handle zeros - Special case for zero values
Consider locale - Some formats vary by region
Test edge cases - Large numbers, negatives, decimals
Memoize expensive operations - Cache formatted values when possible
Type your options - Use TypeScript for format options
Document patterns - Comment non-obvious format strings

Date Handling - Date and time formatting
Validation - Input validation
Tables - Displaying formatted data