Utilities Overview

BuildGrid UI provides a comprehensive set of utility functions, hooks, and TypeScript types to enhance your development experience. These utilities solve common problems and provide reusable functionality across your React applications.

Quick Stats

3

Custom Hooks

2

Formatters

TS

Type Utilities

What are Utilities?

Utilities are helper functions, custom hooks, and TypeScript types that provide common functionality needed in React applications. They include:

• Custom Hooks - Reusable stateful logic
• Formatters - Data formatting functions
• Type Utilities - TypeScript helper types
• Helper Functions - Common utility functions

Custom Hooks

Powerful React hooks for common use cases.

useLocalStorage

Persistent state management with localStorage sync

hookstoragestate

useDebounce

Debounced values for performance optimization

hookperformancedebounce

useCopyToClipboard

Copy text to clipboard with feedback

hookclipboardcopy

Formatters

Utility functions for formatting data consistently.

Currency Formatters

Format monetary values with locale support

formattercurrencylocale

Date Formatters

Format dates and times with various options

formatterdatetime

TypeScript Types

Helper types for better TypeScript development experience.

TypeScript Utilities

Utility types for common TypeScript patterns

typescripttypesutilities

Getting Started

Import utilities directly from the main package:

npm install buildgrid-ui

import { 
  useLocalStorage, 
  useDebounce, 
  useCopyToClipboard,
  formatCurrency,
  formatDate 
} from 'buildgrid-ui'

function MyComponent() {
  // Persistent state with localStorage
  const [name, setName] = useLocalStorage('userName', '')
  
  // Debounced search value
  const [search, setSearch] = useState('')
  const debouncedSearch = useDebounce(search, 300)
  
  // Copy to clipboard functionality
  const { copyToClipboard, isCopied } = useCopyToClipboard()
  
  // Format currency and dates
  const price = formatCurrency(29.99, 'USD')
  const date = formatDate(new Date(), 'MMM dd, yyyy')
  
  return (
    <div>
      <input 
        value={name}
        onChange={(e) => setName(e.target.value)}
        placeholder="Your name (saved to localStorage)"
      />
      
      <input 
        value={search}
        onChange={(e) => setSearch(e.target.value)}
        placeholder="Search (debounced)"
      />
      
      <button onClick={() => copyToClipboard('Hello World!')}>
        {isCopied ? 'Copied!' : 'Copy Text'}
      </button>
      
      <p>Price: {price}</p>
      <p>Date: {date}</p>
    </div>
  )
}

Hook Examples

useLocalStorage

Synchronize state with localStorage automatically:

const [settings, setSettings] = useLocalStorage('appSettings', {
  theme: 'dark',
  language: 'en'
})

// Updates both state and localStorage
setSettings({ ...settings, theme: 'light' })

useDebounce

Optimize performance by debouncing rapid changes:

const [query, setQuery] = useState('')
const debouncedQuery = useDebounce(query, 500)

// API call only happens after user stops typing for 500ms
useEffect(() => {
  if (debouncedQuery) {
    searchAPI(debouncedQuery)
  }
}, [debouncedQuery])

useCopyToClipboard

Easy clipboard operations with feedback:

const { copyToClipboard, isCopied, error } = useCopyToClipboard()

const handleCopy = () => {
  copyToClipboard('Text to copy')
}

return (
  <button onClick={handleCopy}>
    {isCopied ? 'Copied!' : 'Copy'}
    {error && <span>Failed to copy</span>}
  </button>
)

Formatter Examples

Currency Formatting

import { formatCurrency } from 'buildgrid-ui'

// Basic formatting
formatCurrency(1234.56) // "$1,234.56"
formatCurrency(1234.56, 'EUR') // "€1,234.56"
formatCurrency(1234.56, 'USD', 'en-US') // "$1,234.56"

// With options
formatCurrency(1234.56, 'USD', 'en-US', {
  minimumFractionDigits: 0,
  maximumFractionDigits: 0
}) // "$1,235"

Date Formatting

import { formatDate, formatRelativeTime } from 'buildgrid-ui'

const date = new Date('2024-01-15')

// Various formats
formatDate(date, 'MM/dd/yyyy') // "01/15/2024"
formatDate(date, 'MMM dd, yyyy') // "Jan 15, 2024"
formatDate(date, 'EEEE, MMMM do, yyyy') // "Monday, January 15th, 2024"

// Relative time
formatRelativeTime(date) // "2 days ago" (relative to now)

TypeScript Utilities

Helper types for common patterns:

import type { 
  Optional, 
  Prettify, 
  DeepPartial,
  NonEmptyArray 
} from 'buildgrid-ui'

// Make specific properties optional
type User = {
  id: string
  name: string
  email: string
}

type CreateUser = Optional<User, 'id'> // id is optional

// Flatten complex types for better IntelliSense
type ComplexType = Prettify<User & { settings: UserSettings }>

// Make all properties optional recursively
type PartialUser = DeepPartial<User>

// Ensure array has at least one item
type Categories = NonEmptyArray<string>

Best Practices

Performance

• Use useDebounce for search inputs and API calls
• Leverage useLocalStorage for user preferences
• Implement useCopyToClipboard for better UX

Formatting

• Use consistent currency formatting across your app
• Format dates according to user locale
• Provide fallbacks for formatting errors

TypeScript

• Use utility types to create cleaner interfaces
• Leverage type helpers for better IntelliSense
• Create reusable type patterns with utilities

Advanced Usage

Custom Hook Composition

Combine hooks for complex functionality:

function useSearchWithHistory() {
  const [query, setQuery] = useState('')
  const [history, setHistory] = useLocalStorage('searchHistory', [])
  const debouncedQuery = useDebounce(query, 300)
  
  const addToHistory = (searchTerm: string) => {
    setHistory(prev => [searchTerm, ...prev.slice(0, 9)]) // Keep last 10
  }
  
  useEffect(() => {
    if (debouncedQuery) {
      addToHistory(debouncedQuery)
    }
  }, [debouncedQuery])
  
  return { query, setQuery, debouncedQuery, history }
}

Custom Formatters

Extend built-in formatters:

import { formatCurrency } from 'buildgrid-ui'

function formatPrice(amount: number, showFree = true) {
  if (amount === 0 && showFree) {
    return 'Free'
  }
  return formatCurrency(amount)
}

Need Help?

• 📖 Browse individual utility documentation in the sidebar
• 🎨 View live examples in our Storybook
• 💬 Join discussions on GitHub
• 🐛 Report issues on GitHub Issues