Livewire Phone Input Laravel Package

Product Decisions This Supports

• Build vs. buy for phone capture. A phone field looks trivial and isn't: country detection, formatting-as-you-type, E.164 normalization, and dial-code UI are a recurring source of QA bugs and locale complaints. This package is a candidate to remove that from your backlog — the decision it informs is "do we spend a sprint on a phone input, or a day integrating one?"
• Design-system conformance. Styling is driven entirely through a classes config (base parts plus state variants), so the component can be made to look native to your Tailwind design system without forking the view. That makes it viable for products with a branded UI, where an off-the-shelf widget with hardcoded styles would be rejected.
• Feature scoping for international launches. Whether phone capture is a v1 requirement or a "US-only, revisit later" shortcut is a roadmap decision with real downstream cost (stored numbers that can't be normalized, re-collection later). Adopting a component that formats and normalizes internationally lets you defer the geo-expansion decision cheaply rather than pre-committing.
• Risk to price into releases. v1.0.1 is documentation-only — no code changed. The signal is stability, but the three documented traps are operational, not cosmetic (see below), and belong in your upgrade/runbook planning rather than in the feature decision itself.
• Not a decision this supports: fraud/carrier lookup, SMS deliverability, or OTP flows. This is an input component; don't let it absorb scope from identity-verification work.

When to Consider This Package

Consider adoption when most of these hold:

• Your stack is Laravel + Livewire and the phone field lives in a Livewire form. On React/Vue/Inertia-driven frontends, the integration value largely evaporates — evaluate a JS-native alternative instead.
• You need international numbers and want formatting/normalization handled for you rather than hand-rolled.
• You have a Tailwind-based design system and the ability to style via a classes config. The config-driven approach is the selling point; a team that will fight it with CSS overrides gets less value.
• Your team is small enough that a maintained component beats a bespoke one, and you accept a third-party dependency in a user-facing, moderately sensitive path.
• You can absorb the three documented setup constraints:
  • Tailwind won't scan config/ — configured class names are stripped from the build unless you add the file via @source. Budget for one confusing "why is my styling gone in production only" incident if unaddressed.
  • State variants that set the same property as their base part tie, and emit order wins, not authoring order — you'll need !important on the variant. Subtle and non-obvious; document it for whoever owns styling.
  • Publishing pins the config, not just the view, so a published config/phone-input.php won't pick up keys added in later versions. Decide up front: publish only if you must override, and diff the config on upgrade.

Look elsewhere when:

• You need a framework-agnostic or non-Livewire component.
• You require carrier intelligence, validation beyond format/parse, or OTP — this is an input, not a verification product.
• You need guaranteed long-term API/config stability with a formal support commitment; a v1.x package with a config-pinning gotcha warrants a named owner internally.
• You can't take any third-party dependency on the registration path, or your security review treats form inputs as a supply-chain surface and the maintenance signal doesn't clear the bar. Validate maintenance activity, test coverage, and issue responsiveness before committing — the release history here is thin enough that this should be an explicit check, not an assumption.

How to Pitch It (Stakeholders)

For executives: Phone number entry is a deceptively expensive field — country handling, formatting, and normalization generate a steady trickle of bugs and support tickets, and getting it wrong produces unusable stored data that costs more to fix later. This package buys that capability for a Laravel/Livewire app instead of building it: a day of integration versus roughly a sprint of engineering plus ongoing maintenance. v1.0.1 changed no code — it's documentation hardening, which is the right signal at this stage. The main caveat is dependency risk in a user-facing path, so we should assign an owner and pin the version.

For engineering: Livewire component for phone input, styled entirely through a classes config (base parts + state variants) so it fits our Tailwind system without forking the view. Three things to plan for, all documented in v1.0.1 and all non-obvious: (1) Tailwind doesn't scan config/, so configured class names get tree-shaken out of production builds unless we add the config file with @source; (2) a state variant that sets the same property as its base part resolves as a tie by CSS emit order, not authoring order — mark the variant important; (3) vendor:publish pins the config alongside the view, so a published config/phone-input.php silently stops receiving new keys on upgrade. Recommendation: don't publish the config unless we're actually overriding it, and if we do, treat it as a tracked file to diff on every bump. The release itself is docs-only, so there's no migration work — this is a "write it down before someone loses an afternoon" release, not a functional one.