MatrixUI Logo

Utilities API

Complete API documentation for Matrix UI utility functions that help with performance, ref management, prop merging, and styling.

debounce
Function

Delays function execution until after a specified wait period of inactivity

Signature

function debounce<T extends (...args: unknown[]) => unknown>(
  func: T,
  wait: number
): (...args: Parameters<T>) => void

Parameters

func
T
Required

The function to debounce

wait
number
Required

The number of milliseconds to delay

Returns

(...args: Parameters<T>) => void

A debounced version of the original function

Example

import { debounce } from '@matrix-ui/utils'

// Search as user types, but wait for pause
const handleSearch = debounce((query: string) => {
  console.log('Searching for:', query)
  // Actual search logic here
}, 300)

// Usage in component
const [searchQuery, setSearchQuery] = useState('')

const debouncedSearch = useMemo(
  () => debounce((query: string) => {
    if (query) {
      performSearch(query)
    }
  }, 500),
  []
)

useEffect(() => {
  debouncedSearch(searchQuery)
}, [searchQuery, debouncedSearch])

return (
  <input
    value={searchQuery}
    onChange={(e) => setSearchQuery(e.target.value)}
    placeholder="Search..."
  />
)

Use Cases

  • • Search input handling
  • • API call optimization
  • • Window resize events
  • • Form validation triggers

throttle
Function

Limits function execution to at most once per specified time period

Signature

function throttle<T extends (...args: unknown[]) => unknown>(
  func: T,
  limit: number
): (...args: Parameters<T>) => void

Parameters

func
T
Required

The function to throttle

limit
number
Required

The number of milliseconds between allowed executions

Example

import { throttle } from '@matrix-ui/utils'

// Scroll handler that runs at most every 100ms
const handleScroll = throttle(() => {
  const scrollY = window.scrollY
  // Update scroll position or trigger animations
  setScrollPosition(scrollY)
}, 100)

// Usage in component
useEffect(() => {
  window.addEventListener('scroll', handleScroll)
  return () => {
    window.removeEventListener('scroll', handleScroll)
  }
}, [])

// Button click throttling
const handleButtonClick = throttle(() => {
  // Prevent rapid clicking
  submitForm()
}, 1000)

Debounce vs Throttle

Debounce

Waits for silence, then executes once

Throttle

Executes at regular intervals during activity

Installation

npm install @matrix-ui/utils

# Peer dependencies (if not already installed)
npm install clsx tailwind-merge

Usage Patterns

Performance Utilities

import { debounce, throttle } from '@matrix-ui/utils'

// Search optimization
const debouncedSearch = debounce(searchFunction, 300)

// Scroll handling  
const throttledScroll = throttle(scrollHandler, 16) // ~60fps

Component Utilities

import { composeRefs, mergeProps } from '@matrix-ui/utils'
import { cn } from '@matrix-ui/components'

// Styled component
const StyledButton = forwardRef(({ className, ...props }, ref) => (
  <button
    ref={composeRefs(ref, internalRef)}
    className={cn('btn', className)}
    {...mergeProps(defaultProps, props)}
  />
))