How does browser vCard parsing handle vCard 2.1, 3.0, and 4.0 files?
A dedicated Web Worker unfolds wrapped content lines, decodes Quoted-Printable hex sequences as UTF-8, and extracts every BEGIN:VCARD contact block into typed spreadsheet columns offline inside tab memory. No address book bytes leave your device, so VCF to CSV and Excel exports keep Apple, Google, and Outlook records private across all three vCard versions.
Contact files span decades of format revisions, culminating in the IETF RFC 6350 vCard Format Specification for vCard 4.0. Real exports from iCloud, Android, and desktop Outlook still mix vCard 2.1, 3.0, and 4.0 syntax within the same .vcf bundle.
- Two-stage line unfolding: Strips any leading UTF-8 BOM (
0xEF 0xBB 0xBF), joins RFC continuation lines starting with a space or tab, and merges vCard 2.1 Quoted-Printable lines ending with a soft=break. - Property group normalization: Removes Apple item prefixes such as
item1.EMAILoritem2.TELbefore matching standard property names and strippingmailto:ortel:URI schemes. - Fallback display names: Builds
Full Nameautomatically from structuredNcomponents (Prefix,First,Middle,Last,Suffix) wheneverFNis omitted. - Multi-value unescaping: Decodes escaped
\n,\,,\;, and\\sequences insideNOTE,ORG,ADR, andCATEGORIESproperties without cutting fields at escaped semicolons.
Team directories often travel alongside shared event exports from the same group mailbox. When you also receive .ics schedules alongside contact cards, you can convert iCalendar schedules into spreadsheets in the same local worker environment.
Decoded contact columns and Quoted-Printable UTF-8 rules
Each parsed vCard maps into 21 consistent columns covering names, dual email and phone slots, job metadata, street addresses, websites, birthdays, categories, and notes. Choosing the right output depends on whether your next step is desktop Excel review, database import, or multi-file cleanup.
| Format or version | Encoding handling | Phone and ZIP safety | Best downstream workflow |
|---|---|---|---|
| vCard 2.1 input | Quoted-Printable UTF-8 + Windows-1252 | Preserves raw TEL and ADR strings |
Older Outlook and Android backups |
| vCard 3.0 / 4.0 input | Strict UTF-8 with space/tab unfolding | Keeps TYPE= labels and URL/BDAY |
Apple iCloud and Google Contacts |
| Excel Workbook (.xlsx) | Native UTF-8 OpenXML strings | Explicit inlineStr keeps + and leading 0 |
Direct Excel review and CRM prep |
| CSV (.csv) | Optional UTF-8 BOM (\uFEFF) |
CWE-1236 prefixes leading + on text cells |
Database loaders and Merge CSV |
| TSV (.tsv) | Tab-delimited UTF-8 with optional BOM | CWE-1236 formula protection on data rows | Copy-paste and Unix text pipelines |
Decoding Quoted-Printable Outlook and Android vCards
Older Windows and mobile address books encode non-ASCII names using the IETF RFC 2045 Quoted-Printable Standard, splitting multi-byte characters across trailing = soft line breaks. Splitting lines naively before joining = breaks turns accented letters into unreadable hex fragments.
Our parser tracks QUOTED-PRINTABLE header flags during unfolding, strips trailing soft = markers first, converts every =XX pair into raw bytes, and runs TextDecoder("utf-8") across the complete sequence. Files lacking UTF-8 validity fall back cleanly to Windows-1252 in decodeTextBytes().
Multi-number mapping across 21 spreadsheet columns
Contacts routinely list multiple work, mobile, and home entries separated by TYPE= or bare vCard 2.1 parameters. The parser filters out redundant markers such as VOICE, INTERNET, and PREF so columns like Email 1 Type and Phone 1 Type store concise tags like work, cell, or home.
Primary and secondary entries map directly into Email 1, Email 2, Phone 1, and Phone 2, while organization departments after the first semicolon in ORG join into a dedicated Department column. Multiple NOTE lines concatenate with clean line breaks inside the Notes cell.
Merging duplicate contacts and converting CSV back to VCF
Address books exported across phones, mail clients, and CRM tools frequently contain overlapping entries for the same person. Enabling deduplication before export consolidates fragmented contact details, and switching direction turns cleaned spreadsheets back into portable .vcf files.
Smart contact deduplication by email and phone
Leaving Merge duplicate contacts by email / phone checked indexes each contact by lowercased Email 1 first and digit-only Phone 1 (7 or more digits) second. When a later vCard matches an existing person, blank attributes such as Birthday, Title, or City backfill automatically onto the surviving record.
If a duplicate card carries a different Phone 1 or Email 1, the merger promotes that value into Phone 2 or Email 2 rather than discarding it. The preview subtitle reports both the deduplicated count and the original raw card count immediately.
Tip: Click Load sample VCF to inspect a 3-card sample containing vCard 2.1 Quoted-Printable German accents (
Jürgen Müller) and two overlappingClaire Mercercards before processing your own address book.
Converting CRM spreadsheets into vCard 3.0 files
Switching mode to CSV / Excel -> VCF (or dropping any .csv, .tsv, or .xlsx file) runs rowsToVcf() inside the worker to map flexible header names back into CRLF-delimited vCard 3.0 records. The mapper matches aliases including Full Name, First Name, Last Name, Email, Phone, Organization, Title, Street, City, Region, Postal Code, Country, Website, and Notes.
When Full Name is absent, the builder combines First Name and Last Name into FN: automatically and escapes commas, semicolons, backslashes, and newlines. For printed cards or event badges from the same directory, you can also produce offline QR contact cards ready for sharing directly in your browser.
Choosing Excel, CSV, or TSV and preventing formula injection
Plain CSV files look simple until desktop spreadsheet tools evaluate international plus (+) signs in phone numbers or strip leading zeros from postal codes. Comparing Excel vs CSV phone formatting and reviewing how .xlsx XML cells behave prevents silent data corruption after download.
Excel inlineStr cells vs CSV formula neutralization
Selecting Excel Workbook (.xlsx) writes a single Contacts worksheet with bold Calibri 11 pt headers and auto-fitted column widths clamped between 8 and 60 characters. Every string cell uses explicit OpenXML t="inlineStr" markup, preserving +1-206-555-0148 and 08053 postal codes verbatim without formula evaluation.
By contrast, CSV (.csv) and TSV (.tsv) quote embedded commas, tabs, and line breaks according to the IETF RFC 4180 CSV Format Specification so multi-line addresses stay intact across rows.
Because desktop spreadsheets treat leading operators as formulas, exported data rows also apply the MITRE CWE-1236 Formula Injection Standard. Cells beginning with =, +, @, |, or non-numeric - receive a protective leading apostrophe (') so untrusted contact notes or international + phone prefixes never execute as active formulas.
UTF-8 BOM settings and 200-row preview behavior
Keeping Include UTF-8 BOM for Excel import enabled prepends the three-byte \uFEFF marker to .csv and .tsv downloads so Windows Excel recognizes accented names on double-click. Uncheck that option when feeding CSV output into SQL importers, Python scripts, or Unix tools that reject BOM bytes in row 1.
The interactive preview table renders up to 200 rows so large address books stay responsive in the browser UI. Clicking Download XLSX, Download CSV, or Download TSV always exports every contact parsed in everyday.worker.ts, and you can format exported contact CSVs into Excel workbooks anytime if you later decide to style columns in .xlsx.