@yhattav/react-component-cursor/dist/index.d.ts

A lightweight, TypeScript-first React library for creating beautiful custom cursors with SSR support, smooth animations, and zero dependencies. Perfect for interactive websites, games, and creative applications.

import * as React from 'react';

type NullablePosition = {
    x: number | null;
    y: number | null;
};
type CursorPosition = {
    x: number;
    y: number;
};
type CursorOffset = {
    x: number;
    y: number;
};
type CursorVisibilityReason = 'container' | 'disabled' | 'touch' | 'reducedMotion' | 'accessibility' | string;
type CursorMoveHandler = (position: CursorPosition) => void;
type CursorVisibilityHandler = (isVisible: boolean, reason: CursorVisibilityReason) => void;
type CursorState = 'idle' | 'hover' | 'click' | 'drag' | string;
type CursorMode = 'default' | 'pointer' | 'text' | 'grab' | 'grabbing' | string;

interface CustomCursorProps {
    id?: string;
    enabled?: boolean;
    children?: React.ReactNode;
    className?: string;
    style?: React.CSSProperties;
    zIndex?: number;
    offset?: CursorOffset | {
        x: number;
        y: number;
    };
    smoothness?: number;
    containerRef?: React.RefObject<HTMLElement>;
    centered?: boolean;
    throttleMs?: number;
    showDevIndicator?: boolean;
    onMove?: CursorMoveHandler;
    onVisibilityChange?: CursorVisibilityHandler;
    'data-testid'?: string;
    role?: string;
    'aria-label'?: string;
}
declare const CustomCursor: React.FC<CustomCursorProps>;

/**
 * SSR (Server-Side Rendering) utility functions
 * Provides safe detection and handling of server-side rendering environments
 */
/**
 * Detects if the code is running in a server-side rendering environment
 * @returns true if running on server (SSR), false if running in browser
 */
declare const isSSR: () => boolean;
/**
 * Detects if the code is running in a browser environment
 * @returns true if running in browser, false if running on server
 */
declare const isBrowser: () => boolean;
/**
 * Safely executes a function only in browser environment
 * @param fn Function to execute in browser
 * @param fallback Optional fallback value to return in SSR
 * @returns Result of function or fallback value
 */
declare const browserOnly: <T>(fn: () => T, fallback?: T) => T | undefined;
/**
 * Safely gets the document object, handling SSR
 * @returns document if in browser, null if in SSR
 */
declare const safeDocument: () => Document | null;
/**
 * Safely gets the window object, handling SSR
 * @returns window if in browser, null if in SSR
 */
declare const safeWindow: () => Window | null;

export { type CursorMode, type CursorMoveHandler, type CursorOffset, type CursorPosition, type CursorState, type CursorVisibilityHandler, type CursorVisibilityReason, CustomCursor, type CustomCursorProps, type NullablePosition, browserOnly, isBrowser, isSSR, safeDocument, safeWindow };