@devmansam/forms

Professional, highly customizable web form components built as native Web Components.

Overview

This package provides two production-ready form components that you can drop into any website with zero configuration. Both forms are built as Web Components, meaning they work everywhere - vanilla JavaScript, React, Vue, Angular, or any other framework.

What's Included

Web Inquiry Form - A comprehensive multi-step form perfect for agencies, freelancers, or businesses collecting detailed client information. Features 5 steps covering personal info, business details, address, service selection, and a review page.

Minimalist Contact Form - A clean contact form with first name, last name, email, phone (optional), and message fields. Perfect for portfolios, landing pages, or anywhere you need a quick contact option.

Why Use These Forms?

• Drop-in Ready - Add one line of code and you have a working, styled form
• Zero Dependencies - No framework requirements, just pure JavaScript
• Fully Customizable - Every color, font, and style can be customized via HTML attributes
• Accessibility First - Complete ARIA labels, screen reader support, and keyboard navigation
• Dark Mode Built-in - Automatic detection with customizable dark theme colors
• Mobile Responsive - Works perfectly on phones, tablets, and desktops
• Production Tested - Used in real projects by DevLeads and portfolio sites

Installation

CDN

Add the script tag to your HTML:

<!-- For the full Web Inquiry Form -->
<script src="https://cdn.jsdelivr.net/gh/DevManSam777/forms@latest/web-inquiry-form.js" defer></script>

<!-- For the Minimalist Contact Form -->
<script src="https://cdn.jsdelivr.net/gh/DevManSam777/forms@latest/contact-form.js" defer></script>

<!-- Or include both -->
<script src="https://cdn.jsdelivr.net/gh/DevManSam777/forms@latest/web-inquiry-form.js" defer></script>
<script src="https://cdn.jsdelivr.net/gh/DevManSam777/forms@latest/contact-form.js" defer></script>

npm with Bundler

Install the package:

npm install @devmansam/forms

Import in your JavaScript:

// Import both forms
import '@devmansam/forms';

// Or import individually
import '@devmansam/forms/web-inquiry-form';
import '@devmansam/forms/contact-form';

npm without Bundler

Install the package:

npm install @devmansam/forms

Use with import maps in your HTML:

<script type="importmap">
{
  "imports": {
    "@devmansam/forms": "./node_modules/@devmansam/forms/index.js",
    "@devmansam/forms/web-inquiry-form": "./node_modules/@devmansam/forms/web-inquiry-form.js",
    "@devmansam/forms/contact-form": "./node_modules/@devmansam/forms/contact-form.js"
  }
}
</script>

<script type="module">
  import '@devmansam/forms';
</script>

Web Inquiry Form

A comprehensive multi-step form for collecting detailed client information including personal details, business information, address, and service preferences.

Basic Usage

<web-inquiry-form
  api-url="https://your-api-endpoint.com/api/leads"
  form-title="Contact Us"
></web-inquiry-form>

Features

• Multi-step progress indicator with 5 steps
• Personal information (name, email, phone)
• Business information (optional)
• Billing address collection
• Service selection
• Review step before submission
• Built-in field validation
• Phone number formatting

Customization Attributes

Basic Configuration

| Attribute | Description | Default | |-----------|-------------|---------| | api-url | API endpoint URL | http://localhost:5000/api/leads | | theme | Force theme: "light", "dark", or auto | Auto-detect | | form-title | Form header text | "Web Development Inquiry" |

Layout & Typography

| Attribute | Description | Default | |-----------|-------------|---------| | border-radius | Corner roundness | 6px | | font-family | Custom font family | System fonts | | font-size | Base font size | 16px | | google-font | Google Font name to load | None |

Light Mode Colors

| Attribute | Description | Default | |-----------|-------------|---------| | primary-color | Main accent color | #3498db | | background-color | Form background | #ffffff | | text-color | General text color | #333333 | | border-color | Border color | #aaaaaa | | button-color | Button background | Same as primary-color | | button-text-color | Button text color | #ffffff | | back-button-color | Back button background | Same as primary-color | | back-button-text-color | Back button text color | Same as button-text-color | | heading-color | Heading text color | Same as text-color | | input-background-color | Input field background | Same as background-color | | input-text-color | Input text color | Same as text-color | | input-border-color | Input border color | Same as border-color | | fieldset-background-color | Fieldset background | Same as background-color | | success-color | Success message color | #4caf50 | | error-color | Error message color | #d32f2f | | progress-color | Progress bar color | Same as primary-color | | asterisk-color | Required field asterisk color | #ef4444 (red) |

Dark Mode Colors

| Attribute | Description | Default | |-----------|-------------|---------| | dark-primary-color | Primary accent for dark mode | #60a5fa | | dark-background-color | Background for dark mode | #1e2026 | | dark-text-color | Text color for dark mode | #e9ecef | | dark-border-color | Border color for dark mode | #495057 | | dark-button-color | Button background for dark mode | Same as dark-primary-color | | dark-button-text-color | Button text for dark mode | #ffffff | | dark-back-button-color | Back button background for dark mode | Same as dark-primary-color | | dark-back-button-text-color | Back button text for dark mode | Same as dark-button-text-color | | dark-heading-color | Heading text for dark mode | Same as dark-text-color | | dark-input-background-color | Input background for dark mode | Same as dark-background-color | | dark-input-text-color | Input text for dark mode | Same as dark-text-color | | dark-input-border-color | Input border for dark mode | Same as dark-border-color | | dark-fieldset-background-color | Fieldset background for dark mode | Same as dark-background-color | | dark-success-color | Success color for dark mode | #4ade80 | | dark-error-color | Error color for dark mode | #f87171 | | dark-progress-color | Progress color for dark mode | Same as dark-primary-color | | dark-asterisk-color | Required field asterisk color for dark mode | #f87171 (lighter red) |

Example: Custom Theme

<web-inquiry-form
  api-url="https://your-api.com/leads"
  form-title="Get In Touch"
  primary-color="#6366f1"
  background-color="#ffffff"
  button-color="#4f46e5"
  button-text-color="#ffffff"
  heading-color="#1e1b4b"
  input-background-color="#f8fafc"
  fieldset-background-color="#f1f5f9"
  success-color="#10b981"
  error-color="#ef4444"
  border-radius="12px"
  google-font="Inter"
  font-size="16px"
></web-inquiry-form>

Form Data Structure

{
  firstName: "...",
  lastName: "...",
  email: "...",
  phone: "...",
  phoneExt: "...",
  businessName: "...",
  businessPhone: "...",
  businessPhoneExt: "...",
  businessEmail: "...",
  businessServices: "...",
  billingAddress: {
    street: "...",
    aptUnit: "...",
    city: "...",
    state: "...",
    zipCode: "...",
    country: "..."
  },
  preferredContact: "phone|email|text|businessPhone|businessEmail",
  serviceDesired: "Web Development|App Development",
  hasWebsite: "yes|no",
  websiteAddress: "...",
  message: "...",
  isFormSubmission: true
}

Screenshots

Dark Mode

Custom Themes

Minimalist Contact Form

A simple, clean contact form for basic inquiries with name, email, and message fields.

Basic Usage

<contact-form
  endpoint="https://your-api-endpoint.com/api/contact"
></contact-form>

Features

• Clean 5-field form (first name, last name, email, phone, message)
• Phone field is optional with automatic formatting
• Minimal, elegant design
• Real-time field validation
• Success/error message notifications
• Smooth animations

Customization Attributes

Basic Configuration

| Attribute | Description | Default | |-----------|-------------|---------| | endpoint | API endpoint URL | https://example.com/api/contact | | theme | Force theme: "light", "dark", or auto | Auto-detect |

Styling

| Attribute | Description | Default | |-----------|-------------|---------| | primary-color | Main accent color and button background | #3b82f6 | | background-color | Form background color | #ffffff | | text-color | Text color for labels and headings | #374151 | | border-color | General border color | #d1d5db | | border-radius | Corner roundness | 6px | | font-family | Custom font family | System fonts | | font-size | Base font size | 14px | | google-font | Google Font name to load | None | | heading | Form heading text | None | | input-background-color | Input field background | Same as background-color | | input-text-color | Input field text color | Same as text-color | | input-border-color | Input field border color | Same as border-color | | button-text-color | Button text color | #ffffff | | heading-color | Form heading text color | Same as text-color | | asterisk-color | Required field asterisk color | #ef4444 (red) | | success-message | Custom success message | "Message sent successfully!" | | error-message | Custom error message | "Failed to send message. Please try again." |

Dark Mode Styling

| Attribute | Description | Default | |-----------|-------------|---------| | dark-primary-color | Primary color for dark mode | #60a5fa | | dark-background-color | Background for dark mode | #1f2937 | | dark-text-color | Text color for dark mode | #f9fafb | | dark-border-color | General border color for dark mode | #4b5563 | | dark-input-background-color | Input background for dark mode | Same as dark-background-color | | dark-input-text-color | Input text color for dark mode | Same as dark-text-color | | dark-input-border-color | Input border color for dark mode | Same as dark-border-color | | dark-button-text-color | Button text color for dark mode | #ffffff | | dark-heading-color | Heading text color for dark mode | Same as dark-text-color | | dark-asterisk-color | Required field asterisk color for dark mode | #f87171 (lighter red) |

Example: Custom Theme

<contact-form
  endpoint="https://your-api.com/contact"
  primary-color="#8b5cf6"
  background-color="#ffffff"
  text-color="#1f2937"
  border-color="#d1d5db"
  input-background-color="#f9fafb"
  input-text-color="#111827"
  input-border-color="#9ca3af"
  button-text-color="#ffffff"
  border-radius="12px"
  google-font="Inter"
  font-size="14px"
  heading="Get In Touch"
  dark-primary-color="#a78bfa"
  dark-background-color="#1f2937"
  dark-text-color="#f9fafb"
  dark-input-background-color="#111827"
  dark-input-text-color="#e5e7eb"
  dark-input-border-color="#6b7280"
  dark-button-text-color="#1f2937"
></contact-form>

Form Data Structure

The contact form sends the following data structure to your endpoint:

{
  firstName: "...",
  lastName: "...",
  email: "...",
  phone: "..." // or "000-000-0000" if not provided,
  message: "...",
  // Additional fields for DevLeads integration:
  businessName: "First Last",
  businessPhone: "",
  businessPhoneExt: "",
  businessEmail: "",
  businessServices: "",
  phoneExt: "",
  textNumber: "",
  preferredContact: "email",
  serviceDesired: "Web Development",
  hasWebsite: "no",
  websiteAddress: "",
  billingStreet: "N/A",
  billingAptUnit: "",
  billingCity: "N/A",
  billingState: "N/A",
  billingZipCode: "00000",
  billingCountry: "USA",
  billingAddress: {
    street: "N/A",
    aptUnit: "",
    city: "N/A",
    state: "N/A",
    zipCode: "00000",
    country: "USA"
  },
  isFormSubmission: true
}

Note: The contact form includes additional fields for DevLeads integration. The main fields you'll use are firstName, lastName, email, phone, and message.

Screenshots

Accessibility

Both forms are built with comprehensive accessibility (a11y) features to ensure they work for all users, including those using screen readers and assistive technologies.

ARIA Labels & Attributes

• Form Structure: All forms include proper role and aria-labelledby attributes
• Input Labels: Every input has associated labels with unique id attributes
• Required Fields: Fields marked with aria-required="true" for screen readers
• Error States: Invalid fields are marked with aria-invalid="true"
• Error Messages: Error messages use role="alert" and aria-live="assertive" for immediate screen reader announcement
• Live Regions: Success/error notifications use aria-live regions for dynamic updates

Multi-Step Form Accessibility (Web Inquiry Form)

• Progress Indicator: Progress bar includes role="progressbar" with aria-valuenow, aria-valuemin, and aria-valuemax
• Step Navigation: Current step marked with aria-current="step"
• Fieldsets: Each step is properly grouped with role="group" and aria-labelledby
• Radio Groups: Radio button groups include role="radiogroup" with proper labeling
• Conditional Fields: Hidden fields use aria-hidden="true" to prevent confusion
• Review Section: Summary area uses role="region" with aria-live="polite" for dynamic content

Keyboard Navigation

• Full keyboard support for all interactive elements
• Tab navigation through all form fields
• Enter key submits forms appropriately
• Multi-step form advances with Enter on valid steps

Screen Reader Support

• Meaningful labels for all inputs and buttons
• Error messages announced immediately when validation fails
• Success messages announced when forms submit successfully
• Progress updates announced as users navigate through multi-step form
• Conditional field visibility properly communicated

Testing

These forms have been tested for accessibility with:

• NVDA (Windows)
• VoiceOver (macOS/iOS)
• JAWS (Windows)
• Keyboard-only navigation

Events

Both forms dispatch custom events you can listen for:

// Form submitted (before API call)
document.addEventListener('form-submit', (event) => {
  console.log('Form data:', event.detail);
});

// Form successfully submitted
document.addEventListener('form-success', (event) => {
  console.log('Success:', event.detail.message);
});

// Form submission error
document.addEventListener('form-error', (event) => {
  console.error('Error:', event.detail.error);
});

Server Requirements

Your API endpoint should:

• Accept POST requests with Content-Type: application/json
• Return 2xx status code for successful submissions
• Return 4xx/5xx status code for errors
• Optionally return JSON with a message property for error details

Browser Compatibility

Works with all modern browsers that support:

• Custom Elements v1
• Shadow DOM v1
• ES6+ JavaScript

Compatible with: Chrome, Firefox, Safari, Edge

Changelog

v1.0.21 (Latest)

• Contact Form: Added red asterisks to required field labels (First Name, Last Name, Email, Message)
• Contact Form: Added heading-color and dark-heading-color attributes for independent heading text color control
• Both Forms: Added asterisk-color and dark-asterisk-color attributes to customize required field asterisk color
• Default asterisk color: #ef4444 (red) for light mode, #f87171 (lighter red) for dark mode
• Asterisk colors can now be customized independently to match your theme

v1.0.20

• Web inquiry form: Added customizable back button colors
• New attributes: back-button-color, back-button-text-color, dark-back-button-color, dark-back-button-text-color
• Back button now matches primary color by default instead of gray
• Back button text color matches main button text color by default
• Contact form: Moved success/error message to appear between textarea and submit button for better visibility on mobile devices

v1.0.19

• Added Google Fonts additional font-weight imports

v1.0.18

• Increase default font-weight on minimalist form

v1.0.17

• Reduced input and text-area padding mon minimalist form

v1.0.16

• Added comprehensive ARIA labels and accessibility attributes to both forms
• All form inputs now include aria-required, aria-invalid, and aria-describedby attributes
• Error messages use role="alert" with aria-live regions for screen reader announcements
• Progress bar in web inquiry form includes proper role="progressbar" with aria attributes
• Radio groups have role="radiogroup" with proper labeling
• Conditional fields toggle aria-hidden appropriately
• Form navigation marked with aria-current="step" for multi-step form
• Added dark mode styles for ARIA alert elements
• Improved screen reader support and keyboard navigation
• Forms now meet WCAG 2.1 AA accessibility standards

v1.0.15

• Web inquiry form: Updated :host max-width from 632px to 600px (both forms now 600px visual width)

v1.0.14

• Increased form widths for better readability on larger screens
• Contact form: Updated max-width from 500px to 600px
• Web inquiry form: Updated :host max-width from 532px to 632px

v1.0.13

• Added input-text-color and dark-input-text-color attributes to contact form for independent control of input field text colors
• Added input-border-color and dark-input-border-color attributes to contact form for independent control of input field border colors
• Fixed attribute inheritance issues where input fields were incorrectly inheriting from general text and border color attributes
• All contact form color attributes now work independently with proper fallback behavior

v1.0.12

• Added letter-spacing to contact form for improved readability (1px on headings, 0.75px on content)

v1.0.11

• Improved mobile responsive design for contact form with optimized font sizes, padding, and spacing on screens below 480px

v1.0.10

• Updated README with complete documentation for contact form attributes including button text color customization

v1.0.9

• Added button-text-color and dark-button-text-color attributes to contact form for customizable button text

v1.0.8

• Restored 768px breakpoint for web-inquiry-form to prevent text overflow on tablets

v1.0.7

• Removed 768px breakpoint (reverted in v1.0.8 due to text overflow)

v1.0.6

• Fixed contact form name field spacing on mobile to be consistent with other form fields

v1.0.5

• Fixed contact form total width to be 500px (including padding) using box-sizing: border-box
• Improved consistency between contact form and web inquiry form sizing

v1.0.4

• Standardized form widths to 564px for better consistency
• Added responsive name field breakpoint at 480px for improved mobile experience

v1.0.2

• Added assets folder to npm package for proper image display in documentation

v1.0.1

• Initial release with web inquiry form and minimalist contact form
• Multi-step form with validation
• Dark mode support
• Full customization via attributes

License

Author

DevManSam - GitHub

Related Projects

• DevLeads - Full lead management system
• Portfolio Template - Professional portfolio template using these forms