https://github.com/conorluddy/crucai
🪝 Crúcaí: Irish for hooks 🪝 Bare at the moment but I'll be building out a library of random, unusual, but sometimes useful, React Hooks
https://github.com/conorluddy/crucai
frontend hooks hooks-api-react javascript react react-components react-hooks reactjs tools typescript ui utilities
Last synced: 8 months ago
JSON representation
🪝 Crúcaí: Irish for hooks 🪝 Bare at the moment but I'll be building out a library of random, unusual, but sometimes useful, React Hooks
- Host: GitHub
- URL: https://github.com/conorluddy/crucai
- Owner: conorluddy
- Created: 2025-02-08T09:12:52.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-23T17:18:59.000Z (12 months ago)
- Last Synced: 2025-09-09T03:43:44.783Z (9 months ago)
- Topics: frontend, hooks, hooks-api-react, javascript, react, react-components, react-hooks, reactjs, tools, typescript, ui, utilities
- Language: TypeScript
- Homepage: https://www.conor.fyi
- Size: 428 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Crúcai 🪝
> **Crúcai** - Irish for "Hooks" - A React Hooks library
A collection of high-performance, zero-dependency (except for React), React hooks for building responsive and interactive UIs.
This is a [Turborepo](https://turbo.build/repo/docs) managed monorepo, with hooks as independent packages published to NPM.
---
 [](https://codecov.io/gh/conorluddy/crucai) 
 
[](https://opensource.org/licenses/MIT)
[](https://www.npmjs.com/package/crucai)
## 📚 Table of Contents
- [Crúcai 🪝](#crúcai-)
- [📚 Table of Contents](#-table-of-contents)
- [🚀 Installation](#-installation)
- [🔌 Hooks Overview](#-hooks-overview)
- [Key Features:](#key-features)
- [Component API:](#component-api)
- [Options:](#options)
- [Key Features:](#key-features-1)
- [Options:](#options-1)
- [📝 License](#-license)
## 🚀 Installation
Hooks can be installed individually, or as a full collection.
Install this whole repo
```bash
npm install crucai
```
Install only specific hook(s)
```bash
npm install @crucai/use-scroll-tracker
npm install @crucai/use-fuzzy-filter
...
```
## 🔌 Hooks Overview
useScrollTracker
A high-performance hook for tracking element visibility and position as users scroll.
```tsx
import { useScrollTracker } from "crucai";
function FadeInElement() {
const { ref, metrics } = useScrollTracker();
return (
This element fades in as it enters the viewport
);
}
```
#### Key Features:
- **Visibility tracking**: Percentage visible, fully/partially visible states
- **Position tracking**: Relative to viewport top, center, bottom
- **Threshold detection**: Track when element crosses specific visibility points
- **Scroll direction**: Detect up/down scrolling
- **Scroll physics**: Velocity, acceleration, inertia measurements
- **Entry/exit tracking**: Direction, timing, duration
- **High performance**: Uses IntersectionObserver, throttling, and passive events
#### Component API:
The hook also provides a component API using render props:
```tsx
import { ScrollTracker } from "crucai";
function AnimatedElement() {
return (
{(metrics, ref) => (
Animated content
)}
);
}
```
#### Options:
```tsx
const { ref, metrics } = useScrollTracker({
// Visibility thresholds to track (0-100)
thresholds: [0, 25, 50, 75, 100],
// Offset from top/bottom of viewport (e.g., for fixed headers/footers)
offsetTop: 0,
offsetBottom: 0,
// Custom scroll container instead of window
root: containerRef,
// Other options for fine-tuning
rootMargin: "0px 0px 0px 0px",
disabled: false,
throttleDelay: 0,
// Physics-based animation control
dynamics: {
inertiaDecayTime: 300,
maxVelocity: 1000,
easing: "easeInOut",
customEasingPoints: [0.33, 1, 0.68, 1],
},
});
```
> 💡 **Performance Tip:** The hook is optimized to prevent re-renders when metrics haven't changed significantly, making it suitable for scroll-based animations without performance degradation.
useFuzzyFilter
A powerful hook for fuzzy text filtering with advanced matching capabilities.
```tsx
import { useFuzzyFilter } from "crucai";
function SearchableList({ items }) {
const { filteredItems, setQuery } = useFuzzyFilter({
items,
threshold: 2, // Max Levenshtein distance
});
return (
setQuery(e.target.value)}
placeholder="Search items..."
/>
{filteredItems.map((item, index) => (
- {item}
))}
);
}
```
#### Key Features:
- **Fuzzy searching**: Finds close matches even with typos
- **Levenshtein distance**: Controls how strict the matching is
- **Performance optimized**: Uses trie data structure for efficient filtering
- **Customizable**: Set match thresholds and search keys
#### Options:
```tsx
const { filteredItems, setQuery } = useFuzzyFilter({
// Items to filter (strings or objects)
items: ["apple", "banana", "orange"],
// If items are objects, specify which keys to search in
keys: ["name", "description"],
// Maximum Levenshtein distance for a match (default: 2)
threshold: 2,
// Initial search query (optional)
initialQuery: "",
// Whether to match entire query or individual words (default: false)
matchByWord: true,
// Sort results by relevance (default: true)
sortResults: true,
});
```
> 🔍 **Tip:** Using a lower threshold (1-2) provides stricter matching, while higher values (3+) allow more fuzzy results.
## 📝 License
This project is licensed under the MIT License