https://github.com/farisnceit/react-idle-screensaver
A lightweight React component and hook for detecting user inactivity and displaying a customizable idle screensaver. Ideal for kiosks, dashboards, TVs, and unattended React applications. Fully typed and compatible with React 18+
https://github.com/farisnceit/react-idle-screensaver
jsplugin kiosks kiosks-screensaver react react-screensaver reactjs reactplugin
Last synced: 5 months ago
JSON representation
A lightweight React component and hook for detecting user inactivity and displaying a customizable idle screensaver. Ideal for kiosks, dashboards, TVs, and unattended React applications. Fully typed and compatible with React 18+
- Host: GitHub
- URL: https://github.com/farisnceit/react-idle-screensaver
- Owner: farisnceit
- License: other
- Created: 2026-01-06T06:00:19.000Z (5 months ago)
- Default Branch: master
- Last Pushed: 2026-01-23T02:32:48.000Z (5 months ago)
- Last Synced: 2026-01-23T05:53:27.107Z (5 months ago)
- Topics: jsplugin, kiosks, kiosks-screensaver, react, react-screensaver, reactjs, reactplugin
- Language: TypeScript
- Homepage:
- Size: 163 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# @mohamedfariz/react-idle-screensaver
A lightweight, TypeScript-first React library for detecting user inactivity and displaying customizable screensaver overlays.
Built for **kiosks, dashboards, TVs, digital signage, and unattended React applications**.
Compatible with **React 18+** and designed to be **tree-shakable, SSR-safe, and bundler-friendly**.
---
## ✨ Features
- Idle / inactivity detection
- Pluggable screensaver components
- Built-in screensavers included
- React 18+ compatible
- TypeScript-first API with `.d.ts`
- CSS-based styling (no inline styles)
- Tree-shakable and Rollup-friendly
- Safe for kiosk / long-running displays
---
## 📦 Installation
```bash
npm install @mohamedfariz/react-idle-screensaver@beta
```
or
```bash
yarn add @mohamedfariz/react-idle-screensaver@beta
```
or
```bash
pnpm add @mohamedfariz/react-idle-screensaver@beta
```
or
```bash
bun add @mohamedfariz/react-idle-screensaver@beta
```
## 🎨 Import CSS
```tsx
import '@mohamedfariz/react-idle-screensaver/style.css';
```
## Basic Usage
```tsx
import { ScreensaverManager, MatrixScreensaver } from '@mohamedfariz/react-idle-screensaver';
function App() {
return (
My Application
);
}
export default App;
```
## 🧩 Using a Custom Screensaver
Create your own custom screensaver component and pass it to the `ScreensaverManager`:
```tsx
import { ScreensaverManager } from '@mohamedfariz/react-idle-screensaver';
const MyScreensaver = () => (
Custom Screensaver Content
);
function App() {
return ;
}
export default App;
```
### Passing Props to Custom Screensaver
You can pass custom props to your screensaver component:
```tsx
interface CustomScreensaverProps {
message: string;
showLogo?: boolean;
}
const MyScreensaver: React.FC = ({ message, showLogo }) => (
{showLogo && (
)}
{message}
);
function App() {
return (
);
}
```
### Using Screensaver Context
Access screensaver state and controls from within your custom component:
```tsx
import { ScreensaverContext } from '@mohamedfariz/react-idle-screensaver';
import { useContext } from 'react';
const MyScreensaver = () => {
const { stopScreensaver } = useContext(ScreensaverContext);
return (
Tap to Continue
);
};
```
## 🛠 Built-in Screensavers
| Component | Description |
| ---------------------- | --------------------------------------------- |
| BouncingScreensaver | Floating badge that bounces around the screen |
| MatrixScreensaver | Matrix-style falling characters |
| ImageSliderScreensaver | Fullscreen image slideshow with clock |
| StarfieldScreensaver | Animated starfield / space-warp effect |
## 📘 API Reference
Prop Type Default Description
component ComponentType — Screensaver component
componentProps T {} Props passed to screensaver
timeout number 5000 Idle timeout (ms)
active boolean true Enable / disable screensaver
zIndex number 50 Overlay z-index
onScreenSaverStop () => void — Callback when user resumes
## 🔧 Hook: useIdleTimer
```tsx
import { useIdleTimer } from "@mohamedfariz/react-idle-screensaver";
const isIdle = useIdleTimer(timeout?, active?);
```
## 🎯 Intended Use Cases
- Kiosks and digital signage
- Unattended applications
- TV and dashboard interfaces
- Long-running displays
- Public or unattended terminals
## ⚠️ Notes & Limitations
- Browser-only (no Node rendering)
- Consumers must import CSS explicitly