PIO.js

PIO (Persistent Input/Output) is a lightweight, dependency-free JavaScript library that automatically saves and restores form state using the modern File System Access API. Never lose user input again across page reloads!

---

Features

• Automatic State Persistence - Form values saved in real-time
• Zero Configuration - Just add the stateful attribute
• Zero Dependencies - Pure vanilla JavaScript
• Tiny Footprint - < 3KB minified
• Privacy-First - All data stored locally in the browser
• Framework Agnostic - Works with React, Vue, vanilla JS, etc.
• Modern API - Built on File System Access API
• TypeScript Ready - Written in TypeScript with full type definitions

---

Quick Start

Installation

<script type="module" src="pio.min.js"></script>

Basic Usage

Add the stateful attribute to any form element:

<input type="text" stateful placeholder="This value persists!" />
<textarea stateful rows="4"></textarea>
<select stateful>
    <option value="1">Option 1</option>
    <option value="2">Option 2</option>
</select>

That's it! PIO automatically:

1. Detects elements with the stateful attribute
2. Saves their values as users type
3. Restores values on page reload

---

Documentation

• API Reference - Complete API documentation
• Usage Examples - Real-world examples and patterns
• Contributing Guide - How to contribute
• Changelog - Version history

---

Use Cases

Perfect for:

• Long forms - Prevent data loss from accidental refreshes
• Multi-step wizards - Preserve progress across steps
• Draft comments - Save blog comments or forum posts
• Search filters - Remember user preferences
• User settings - Persist configuration choices
• Survey forms - Allow users to complete over multiple sessions

Not suitable for:

• Passwords or sensitive data - Use secure authentication instead
• Payment information - Use PCI-compliant payment processors
• Cross-device sync - Use a backend database instead

---

Examples

Contact Form

<form>
    <input type="text" id="name" stateful placeholder="Your name" />
    <input type="email" id="email" stateful placeholder="Your email" />
    <textarea id="message" stateful rows="5"></textarea>
    <button type="submit">Send</button>
</form>

User Preferences

<select id="theme" stateful>
    <option value="light">Light Theme</option>
    <option value="dark">Dark Theme</option>
    <option value="auto">Auto</option>
</select>

<label>
    <input type="checkbox" id="notifications" stateful />
    Enable notifications
</label>

Radio Buttons

<input type="radio" name="color" value="red" stateful /> Red
<input type="radio" name="color" value="blue" stateful /> Blue
<input type="radio" name="color" value="green" stateful /> Green

See EXAMPLES.md for more detailed examples.

---

Building from Source

Prerequisites

• Deno 1.x or higher

Build

# Production build
deno task build

# Development mode (watch for changes)
deno task dev

Output: web/pio.min.js

---

Browser Compatibility

PIO requires the File System Access API, which is available in:

• Chrome 86+
• Edge 86+
• Opera 72+
• Firefox: Behind flag (not production-ready)
• Safari: Not supported

Feature Detection:

if ('storage' in navigator && 'getDirectory' in navigator.storage) {
    console.log('PIO is supported!');
} else {
    console.warn('Browser does not support File System Access API');
}

---

Optional Stylesheet

PIO includes an optional opiniated stylesheet (pio.css) for beautiful form styling:

<link rel="stylesheet" href="pio.css" />
<script type="module" src="pio.min.js"></script>

The stylesheet will be automatically detected and loaded. If not found, PIO applies basic default styles.

---

Security & Privacy

Local-Only Storage

• All data is stored locally in the user's browser
• No data is transmitted to external servers
• Data persists only on the device where it was created

Permissions

• PIO requests persistent storage permission from the browser
• Users can revoke permissions at any time via browser settings

Best Practices

1. Use stateful only for non-sensitive data
2. Provide a "Clear Data" button for user control
3. Inform users that their data is being saved
4. Never persist passwords, credit cards, or PII

---

Advanced Usage

Accessing the PIO Instance

if (window.pio.ready) {
    console.log('PIO is initialized and ready!');
}

Clearing Stored State

async function clearAllState() {
    const root = await navigator.storage.getDirectory();
    const pioDir = await root.getDirectoryHandle('pio', { create: false });
    
    for await (const entry of pioDir.values()) {
        if (entry.name !== 'config.json') {
            await pioDir.removeEntry(entry.name);
        }
    }
}

Debugging

View stored data in Chrome DevTools:

1. Application tab
2. Storage → File System
3. Select your origin → pio/

---

Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

• Development setup
• Coding standards
• Testing guidelines
• Pull request process

Quick Contribution Guide

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes
4. Build and test: deno task build
5. Commit: git commit -m "feat: add my feature"
6. Push: git push origin feature/my-feature
7. Create a Pull Request

---

Project Statistics

• Language: TypeScript
• Size: < 3KB minified
• Dependencies: Zero
• Build Tool: Deno
• License: MIT

---

License

PIO is released under the MIT License.

MIT License

Copyright (c) 2026 VisionMise

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

See LICENSE for the full license text.

---

Acknowledgments

• Built with Deno
• Uses the File System Access API
• Inspired by the need for better form state management

---

Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Website: Demo and Documentation

---

Show Your Support

If you find PIO useful, please consider:

• Starring the repository
• Reporting bugs
• Suggesting features
• Contributing code
• Sharing with others

---

Made with love by VisionMise