@t007/input

An advanced, highly customizable, and fully automated vanilla JavaScript form management system. Features floating labels, automatic validation, mutation observing, and native file-size enforcement.

Live Demo | Report Bug

Table of contents

• @t007/input
  • Table of contents
  • Overview
  • Demo & Screenshots
  • Features
  • Tech Stack
  • Getting Started
  • Usage
  • API Reference
  • Advanced Usage
  • Customization
  • Author
  • Acknowledgments
  • Star History

Overview

@t007/input is a powerful Form Manager (FM) designed to take the pain out of HTML5 forms. It automatically handles floating labels, injects custom icons, tracks password strength, and strictly enforces validation rules (including deep file-size and mime-type checks) without requiring a massive framework.

Why @t007/input?

• ✅ DOM Mutation Auto-Tracking: Automatically initializes new inputs added to the DOM dynamically.
• ✅ Advanced File Validation: Built-in checks for maxSize, minSize, maxTotalSize, and specific MIME types.
• ✅ Intelligent Password UX: Ships with a built-in password strength meter, confirm-password matching, and toggleable visibility icons.
• ✅ Zero Frameworks: Pure vanilla JS. Drop it into React, Vue, or a static HTML site.
• ✅ Global Injection: Automatically attaches to window.field and window.handleFormValidation for instant legacy integration.

Demo & Screenshots

Standard Input Fields

Beautiful floating labels with native error state handling.

Mobile & Responsive State

Form Validation in Action

Features

• Programmatic Field Generation: Create complex DOM inputs (with icons, meters, and helpers) via a single JS object.
• Client & Server Sync: Supports form.validateOnServer() hooks before allowing submission.
• Automatic Error Shaking: Visual feedback (shake animation) on invalid focus-out or submit.
• Horizontal Scroll Assist: Built-in helper for long error messages overflowing the container.
• Tree-Shakeable: Import only the utilities you need.

Vanilla Perks & Hooks

• form.onSubmit: Optional callback on a form that runs instead of form.submit() when provided, allowing custom JS submission flows.
• form.validateOnServer: Async hook; if defined the form will await its result before proceeding. Returning false prevents submission and shows a global error.
• form.validateOnClient: Reference to the internal client-side validation function, allowing you to trigger validation manually or integrate it into custom UI flows.
• form.toggleGlobalError(bool): Programmatic API to display a form-level error state and shake all fields, used internally if form.validateOnServer returns false.

Tech Stack

Built with

• Vanilla JavaScript (ES6+)
• HTML5 Form Validation API
• MutationObserver API
• Bundled via tsup (ESM, CJS, IIFE outputs)

Getting Started

Installation

Install via your preferred package manager:

npm install @t007/input
# or
yarn add @t007/input
# or
pnpm add @t007/input

Usage

Modern Bundlers (ESM)

import '@t007/input/style.css';
import { field, handleFormValidation, formManager } from '@t007/input'; // also attached to window.t007

// 1. Create a complex input field programmatically
const emailInput = field({
  type: 'email',
  label: 'Email Address',
  placeholder: 'Enter your email',
  required: true,
  helperText: {
    info: "We'll never share your email.",
    typeMismatch: "Please enter a valid email address."
  }
});

// 2. Append to a form
const myForm = document.querySelector('.t007-input-form');
myForm.appendChild(emailInput);

// 3. Initialize the validation engine
handleFormValidation(myForm);

React

import { Input, WordsInput, useFormManager } from "@t007/input/react";

export function SignupForm() {
  const formRef = useRef<HTMLFormElement>(null); // use in a non-form setup or for manual `validate` triggers
  const { handleSubmit, validate, fireInput } = useFormManager((e) => console.log("submitted"), formRef); // first in line to replace browser behaviour effectively

  return (
    <form noValidate className="t007-input-form" onSubmit={handleSubmit} ref={formRef}>
      <Input type="email" label="Email" required helperText={{ typeMismatch: "Enter a valid email." }} />
      <WordsInput type="textarea" label="Bio" maxCount={120} />
      <button type="submit">Submit</button>
    </form>
  );
}

CDN / Browser (Global)

When loaded via a <script> tag, the library automatically scans the DOM for forms with the class .t007-input-form and initializes them.

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@t007/input@latest/dist/index.min.css">
</head>
<body>
  
  <form class="t007-input-form" novalidate>
    <div class="t007-input-field">
      <label class="t007-input-wrapper">
        <span class="t007-input-outline">
          <span class="t007-input-outline-leading"></span>
          <span class="t007-input-outline-notch">
            <span class="t007-input-floating-label">Username</span>
          </span>
          <span class="t007-input-outline-trailing"></span>
        </span>
        <input type="text" class="t007-input" required minlength="3">
      </label>
    </div>
    <button type="submit">Submit</button>
  </form>

  <script src="https://cdn.jsdelivr.net/npm/@t007/input@latest"></script>
</body>
</html>

API Reference

field(config)

Programmatically generates the complex DOM structure required for the floating labels, icons, and error states.

• config.type (String): Standard HTML input type, or "select", "textarea".
• config.label (String): The floating label text.
• config.placeholder (String): Standard placeholder.
• config.options (Array): Used only when type="select". Array of strings or {value, option} objects.
• config.helperText (Object | Boolean): Maps native HTML5 validity states to custom error messages.
  • info: Default helper text.
  • valueMissing: Shown when required fails.
  • typeMismatch: Shown when email/url format fails.
  • (Set to false to disable the helper line entirely).
• config.passwordMeter (Boolean): Enables the 4-tier password strength bar.
• config.eyeToggler (Boolean): Enables the show/hide password icons.
• ...otherProps: Any standard HTML attributes (required, minlength, disabled) are passed directly to the input.

handleFormValidation(formElement)

Attaches the event listeners to a specific form, preventing default submission if inputs are invalid, and triggering the .t007-input-shake animations on errors.

The Form Manager (t007.FM)

The core object injected into the global namespace containing utility functions like togglePasswordType, getFilesHelper, and observeDOMForFields().

Advanced Usage

File Validation

The library extends native file inputs with custom attributes for strict size enforcement, and the same validation logic is available directly through t007.FM.getFilesHelper(files, opts):

const fileUploader = field({
  type: 'file',
  label: 'Upload Avatar',
  accept: 'image/png, image/jpeg',
  multiple: true,
  maxSize: 5000000, // 5MB max per file
  maxTotalSize: 15000000, // 15MB max total upload
  maxLength: 3 // Max 3 files allowed
});

To use the helper directly, map the same fields into getFilesHelper and feed the returned message into your own resolver or helperText path:

const { violation, message } = t007.FM.getFilesHelper(input.files, {
  accept: input.accept, // -> typeMismatch
  multiple: input.multiple, // respects file count limits
  maxSize: input.maxSize, // -> rangeOverflow
  minSize: input.minSize, // -> rangeUnderflow
  maxTotalSize: input.maxTotalSize, // -> rangeOverflow
  minTotalSize: input.minTotalSize, // -> rangeUnderflow
  maxLength: input.maxLength, // -> tooLong
  minLength: input.minLength, // -> tooShort
});

if (message) input.setCustomValidity(message);

Password Management

Setting an input's custom attribute to password or confirm_password automatically links their validation states.

// Master password
field({ type: 'password', custom: 'password', label: 'Password' });

// Confirmation (Automatically errors if it doesn't match the master)
field({ type: 'password', custom: 'confirm_password', label: 'Confirm Password' });

There's other custom features like onward_date, past_date.

Customization

You can deeply customize the look and feel by overriding the built-in CSS variables or targeting the specific classes.

CSS Selectors & Variables

• .t007-input: The actual <input> element.
• .t007-input-floating-label: The label text.
• .t007-input-outline: The border wrapper holding the label.
• [data-error]: Attribute added dynamically on validation failure.
• .t007-input-password-strength-meter: The container for the 4 strength bars.

Override Starter

.t007-input-field {
  --t007-input-color: var(--app-theme-color);
  /* ...check source code for all variables... */
}

Specificity Note

• Start with :root for shared input tokens.
• If a token does not apply, override directly on .t007-input-field.
• For precise control, target element selectors like .t007-input, .t007-input-floating-label, and .t007-input-outline.
• For strong app themes (e.g. html[data-theme="dark"]), use equal/stronger selectors like html[data-theme="dark"] .t007-input-field.
• Check source code for more details.

Author

• Developer - Oketade Oluwatobiloba (Tobi007-del)
• Project - t007-tools

Acknowledgments

Built to provide a robust, dependency-free form validation engine that rivals heavyweight frontend frameworks. Part of the @t007 utility ecosystem.

Star History

If you find this project useful, please consider giving it a star! ⭐