vies-validator

A beautiful React component for validating European VAT numbers against the official VIES REST API. Every field the EU returns is explained inline, in plain language.

• All 27 EU member states + Northern Ireland, with flags and per-country format hints
• Fully typed (TypeScript)
• Zero runtime dependencies (only React as a peer)
• Ships with a polished stylesheet — one import and you’re done
• Works client-side or behind your own proxy (see CORS below)

Install

npm install vies-validator
# or
pnpm add vies-validator
# or
yarn add vies-validator

Use

import { ViesValidator } from 'vies-validator';
import 'vies-validator/style.css';

export default function Page() {
  return <ViesValidator initialCountry="RO" />;
}

Props

| Prop | Type | Default | Description | | ---------------- | ----------------------------------------- | ------------- | ---------------------------------------------------------------- | | initialCountry | string | "RO" | Pre-selected ISO country code | | initialVat | string | "" | Pre-filled VAT number (without country prefix) | | autoLookup | boolean | false | If true, runs a lookup on mount using initial values | | baseUrl | string | VIES official | Override when you proxy the API (see CORS section) | | theme | 'light' \| 'dark' \| 'auto' | 'light' | Colour scheme | | onResult | (r: ViesResponse) => void | | Called after each successful lookup | | className | string | | Extra class for the root element |

Headless usage

You can also call the API directly if you want to build your own UI:

import { lookupVat } from 'vies-validator';

const result = await lookupVat('RO', '54474470');
console.log(result.name);

CORS

The official VIES service does not always send Access-Control-Allow-Origin, so a direct browser call from your domain may be blocked. You have three options:

1. Call it from the browser and hope — in some setups it works; easiest to try first.

2. Proxy through your backend — expose GET /vies/:country/:vat on your own server, forward the request to https://ec.europa.eu/taxation_customs/vies/rest-api/ms/:country/vat/:vat, and return the JSON. Then pass baseUrl="https://your.app/vies" to the component.

3. Use a serverless edge function — Vercel, Cloudflare Workers, Netlify, etc. A minimal Vercel example:

   // api/vies/[country]/[vat].ts
   export default async function handler(req, res) {
     const { country, vat } = req.query;
     const r = await fetch(
       `https://ec.europa.eu/taxation_customs/vies/rest-api/ms/${country}/vat/${vat}`,
     );
     res.status(r.status).json(await r.json());
   }

   Then: <ViesValidator baseUrl="/api/vies" /> — note that the component appends /ms/{country}/vat/{vat} to the base URL.

What the fields mean

The component already surfaces this inline (click the ⓘ button on each field), but for reference:

| Field | Meaning | | --------------------- | ---------------------------------------------------------------------------------------------------- | | isValid | true = registered AND cleared for intra-EU trade at the time of the request. | | userError | Status code: VALID, INVALID, INVALID_INPUT, SERVICE_UNAVAILABLE, MS_UNAVAILABLE, TIMEOUT, GLOBAL_MAX_CONCURRENT_REQ, MS_MAX_CONCURRENT_REQ, INVALID_REQUESTER_INFO. | | requestDate | ISO timestamp — your reference point (VAT status changes over time). | | name | Registered legal name. Some countries (DE, ES) return --- by policy. | | address | Registered address. Same --- caveat as above. | | requestIdentifier | Only returned if you pass a requester VAT. Keep it as legal proof of consultation. | | vatNumber | Normalised (spaces/punctuation stripped). | | originalVatNumber | Exactly what you submitted. | | viesApproximate | Fuzzy match scoring against optional company details you supplied. Codes: 1 match, 2 mismatch, 3 not compared. |

Development

npm install
npm run dev       # demo page at http://localhost:5173
npm run build     # produces the library in ./dist
npm run build:demo  # produces a static site of the demo page

What YOU need to do before publishing

This package is ready to ship, but there are a few human-only steps:

1. Pick a package name. vies-validator may already be taken on npm.

   npm view vies-validator

   If that returns a package, change "name" in package.json to something unique (scoped names are a safe bet: @your-username/vies-validator).
2. Fill in author in package.json (and optionally homepage, repository, bugs).
3. Log in to npm (one-time):

   npm login

4. Build and publish:

   npm run build
   npm publish

   The prepublishOnly hook re-runs the build, and .npmignore keeps source files out of the published tarball. Only dist/, README.md, and LICENSE ship.
5. If you picked a scoped name (@you/vies-validator), use:

   npm publish --access public

   (already configured in publishConfig so this is automatic).
6. Tag a git release (optional but nice):

   git tag v0.1.0 && git push --tags

That’s it. npm install your-package-name will then work anywhere.

License

MIT