VCF Version Converter — vCard 2.1 ⇄ 3.0 Without Losing Photos

Which version do you have?

Look at the VERSION: line. Every vCard this converter accepts is a BEGIN:VCARD … END:VCARD block; convertVcardBlock reads VERSION and replaces it with the target you selected — 2.1, 3.0 or 4.0 — then walks every other property in the same block. The library does not parse the card into a contact and generate a new one. That is why PHOTO payloads, X- fields and item groups survive on the lines they arrived on.

vCard 2.1 is still what old feature phones, SIM-management tools and some Outlook exports write. Those files are the ones with CHARSET and ENCODING=QUOTED-PRINTABLE on name and note lines, and with bare type words such as TEL;CELL;PREF. vCard 3.0 is the interchange version Android, iPhone, Google Contacts and iCloud use: UTF-8 in the value, TYPE=CELL,PREF, PHOTO;ENCODING=b. vCard 4.0 is RFC 6350 — modern apps, TYPE values in lowercase, PREF=1 as its own parameter, inline photos as a data:image/jpeg;base64,... URI.

The drop zone counts how many cards sit at 2.1, 3.0, 4.0 or an unknown VERSION before you convert. An unknown VERSION is replaced with VERSION:<target>; a missing VERSION line is not inserted, but other properties are still rewritten for the target. If the target itself is not one of 2.1, 3.0 or 4.0, the library falls back to 3.0.

What changes from 2.1 to 3.0

When you pick 3.0, type words are uppercased and joined as a single TYPE= parameter, with PREF added as a TYPE token rather than a separate parameter. Quoted-printable is decoded first. The table is the exact form lib/vcfVersion.js emits — the same strings scripts/test-vcfversion.mjs asserts.

CHARSET is honoured on quoted-printable values: ISO-8859-1, LATIN-1 and LATIN1 are read as Latin-1 (Caf=E9 → Café); any other CHARSET, including UTF-8, is decoded as UTF-8 (Garc=C3=ADa → García). After decode, the CHARSET and ENCODING parameters are dropped, so 3.0 writes a plain N:García;Ana;;; line. The PHOTO payload is not re-encoded — only the parameter spelling changes from JPEG;ENCODING=BASE64 to TYPE=JPEG;ENCODING=b.

The same select also offers 4.0. That target is a different parameter style: TEL;TYPE=cell;PREF=1:+15550101, EMAIL;TYPE=internet:, and PHOTO:data:image/jpeg;base64,<payload>. FN is synthesized from N for 4.0 the same way it is for 3.0.

3.0 to 2.1

The other direction exists because old Nokia, Symbian and SIM importers still reject 3.0. TYPE=CELL,PREF becomes the 2.1 bare words TEL;CELL;PREF; TYPE=INTERNET becomes EMAIL;INTERNET. A PHOTO;TYPE=JPEG;ENCODING=b line becomes PHOTO;JPEG;ENCODING=BASE64 with the same payload.

Non-ASCII text is the reason 2.1 files look ugly in a text editor. The rewriter encodes any value with a character outside printable ASCII as quoted-printable and labels it CHARSET=UTF-8;ENCODING=QUOTED-PRINTABLE. scripts/test-vcfversion.mjs checks that NOTE:café on a 3.0 card becomes a NOTE line ending :caf=C3=A9 with those two parameters. ASCII values (phones, emails) are not QP-encoded. FN that already exists is kept; FN is not synthesized when the target is 2.1.

A 2.1 → 3.0 → 2.1 round trip is what the test fixture asserts for TEL, EMAIL, the PHOTO payload, X-CUSTOM and item1.X-ABLabel. The name goes back to quoted-printable (Garc=C3=ADa) because 2.1 cannot put García on the line as UTF-8.

What is not converted

This is a property-level rewrite, not a contact mapper. These stay as they are, or are skipped with a warning:

• N and ADR structure. Semicolon-separated fields are not reinterpreted — only the encoding of the value changes, not which slot is given name or street.
• X- lines and item groups (item1.X-ABLabel) are copied through, not mapped into a standard property.
• Unknown parameters that are not TYPE, PREF, CHARSET or a known encoding (QUOTED-PRINTABLE / QP / BASE64 / B) are copied through.
• Malformed lines (no unquoted colon) are skipped. convertVcf collects them as Skipped malformed line: plus the first 120 characters, joins surviving cards with CRLF, and returns that warning list to the preview.
• A PHOTO that is not BASE64 and not a data:URI is not wrapped in a data URI — the line is rewritten with the target's TYPE style only.

4.0 is converted: TYPE values are lowercased, PREF=1 (or the PREF value already on the line) is emitted as its own parameter, and an inline photo becomes a data URI. What this page does not do is transcode a whole file that is Latin-1 or Windows-1252 without quoted-printable — that is a file-encoding problem, not a VERSION rewrite — and it does not drop extra phones, emails or PHOTO the way the VCF editor does when it regenerates from a form.

Fixing garbled names

If names show as García or Garc=C3=ADa, start on the VCF encoding fix page. The four fingerprints (UTF-8 read as Latin-1, quoted-printable left encoded, Latin-1 read as UTF-8, a BOM or UTF-16 dump) each have a different repair.

The viewer, editor and VCF-to-CSV parser decode quoted-printable as UTF-8 and ignore CHARSET. This converter is the one path that honours CHARSET=ISO-8859-1 on QP values. If the file is ANSI or Latin-1 without quoted-printable, re-save it as UTF-8 in a text editor first — this rewrite will not guess a file encoding.

After converting

Open the download in Open a VCF file to confirm names, phones and that the photo is still on the card. That page is a viewer: it does not rewrite VERSION.

To change a swapped last name or a missing plus on a number, use the VCF editor. That path parses each card into a form and regenerates it — photos and custom X- fields are dropped, which is the warning on that page. Keep the converted .vcf as the archive if you still need the pictures.

For a spreadsheet, run the same file through VCF to CSV. The CSV is UTF-8 so Excel shows accents; it is an inspection copy, not the vCard you will import later.

VCF Version Converter — FAQ

• Is my .vcf uploaded anywhere?

  No. convertVcf runs in this tab — there is no upload endpoint. After the page has loaded you can disconnect from the internet and still drop a .vcf, pick 2.1, 3.0 or 4.0, preview the first converted cards, and download. Nothing in lib/vcfVersion.js or the converter component sends your file to a server.

• Which vCard versions can I convert between?

  2.1, 3.0 and 4.0. The target select lists those three. convertVcardBlock rewrites an existing VERSION line to the target you pick; if the target is not one of those three, the library falls back to 3.0. An unknown VERSION is replaced with VERSION:<target>. A missing VERSION line is not inserted — other properties are still rewritten to the selected target.

• What happens to contact photos?

  They stay. A 2.1 PHOTO;JPEG;ENCODING=BASE64 line becomes PHOTO;TYPE=JPEG;ENCODING=b on 3.0 with the same base64 payload. Targeting 4.0 turns an inline photo into PHOTO:data:image/jpeg;base64,<payload>. Going back to 2.1 restores ENCODING=BASE64 and a JPEG type word. A PHOTO that is not BASE64 and not a data URI is not wrapped in a data URI.

• Does CHARSET=ISO-8859-1 actually get honoured?

  Yes, on this page. Quoted-printable values labelled ISO-8859-1, LATIN-1 or LATIN1 are decoded as Latin-1 — Caf=E9 becomes Café. Any other CHARSET, including UTF-8, is decoded as UTF-8 (Garc=C3=ADa → García). The viewer, editor and VCF to CSV parser do not read CHARSET; they always decode quoted-printable as UTF-8. This rewrite is the path that does.

• Why convert a modern vCard back to 2.1?

  Old Nokia, Symbian and SIM importers still expect 2.1 type words (TEL;CELL;PREF, EMAIL;INTERNET) and quoted-printable for non-ASCII text. Targeting 2.1 writes CHARSET=UTF-8;ENCODING=QUOTED-PRINTABLE on any value with a character outside printable ASCII — NOTE:café becomes a NOTE line ending :caf=C3=A9. ASCII phones and emails are not QP-encoded.

• What is not converted?

  N and ADR keep their semicolon-separated structure; the rewriter does not reinterpret given-name versus street. X- lines and item groups (item1.X-ABLabel) are copied through, not mapped. Unknown parameters that are not TYPE, PREF, CHARSET or a known encoding are copied through. Lines with no unquoted colon are skipped and listed as “Skipped malformed line: …”. FN is synthesized from N only when the target is 3.0 or 4.0 and FN is missing — not when targeting 2.1.

• How is this different from the VCF editor?

  The editor parses each card into a form and regenerates it: photos, X- fields, birthdays and a third phone or email are dropped. This converter walks properties in place, so PHOTO payloads, X-CUSTOM and item groups survive. Use the editor when you need to change a name or number; use this page when you need a version change without losing photos.