vcards-js
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/vcards-js package

    2.10.0 • Public • Published

    vCards JS

    Build Status

    Create vCards to import contacts into Outlook, iOS, Mac OS, and Android devices from your website or application.

    Screenshot

    Install

    npm install vcards-js --save

    Usage

    Below is a simple example of how to create a basic vCard and how to save it to a file, or view its contents from the console.

    Basic vCard

    var vCardsJS = require('vcards-js');
     
    //create a new vCard
    var vCard = vCardsJS();
     
    //set properties
    vCard.firstName = 'Eric';
    vCard.middleName = 'J';
    vCard.lastName = 'Nesser';
    vCard.organization = 'ACME Corporation';
    vCard.photo.attachFromUrl('https://avatars2.githubusercontent.com/u/5659221?v=3&s=460', 'JPEG');
    vCard.workPhone = '312-555-1212';
    vCard.birthday = new Date(1985, 0, 1);
    vCard.title = 'Software Developer';
    vCard.url = 'https://github.com/enesser';
    vCard.note = 'Notes on Eric';
     
    //save to file
    vCard.saveToFile('./eric-nesser.vcf');
     
    //get as formatted string
    console.log(vCard.getFormattedString());
     

    On the Web

    You can use vCards JS on your website. Below is an example of how to get it working on Express 4.

     
    var express = require('express');
    var router = express.Router();
     
    module.exports = function (app) {
      app.use('/', router);
    };
     
    router.get('/', function (req, res, next) {
     
        var vCardsJS = require('vcards-js');
     
        //create a new vCard
        vCard = vCardsJS();
     
        //set properties
        vCard.firstName = 'Eric';
        vCard.middleName = 'J';
        vCard.lastName = 'Nesser';
        vCard.organization = 'ACME Corporation';
     
        //set content-type and disposition including desired filename
        res.set('Content-Type', 'text/vcard; name="enesser.vcf"');
        res.set('Content-Disposition', 'inline; filename="enesser.vcf"');
     
        //send the response
        res.send(vCard.getFormattedString());
    });
     

    Embedding Images

    You can embed images in the photo or logo field instead of linking to them from a URL using base64 encoding.

    //can be Windows or Linux/Unix path structures, and JPEG, PNG, GIF formats
    vCard.photo.embedFromFile('/path/to/file.png');
    vCard.logo.embedFromFile('/path/to/file.png');
    //can also embed images via base-64 encoded strings
    vCard.photo.embedFromString('iVBORw0KGgoAAAANSUhEUgAAA2...', 'image/png');
    vCard.logo.embedFromString('iVBORw0KGgoAAAANSUhEUgAAA2...', 'image/png');

    Date Reference

    MDN reference on how to use the Date object for birthday and anniversary can be found at https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date.

    Complete Example

    The following shows a vCard with everything filled out.

    var vCardJS = require('vcards-js');
     
    //create a new vCard
    var vCard = vCardsJS();
     
    //set basic properties shown before
    vCard.firstName = 'Eric';
    vCard.middleName = 'J';
    vCard.lastName = 'Nesser';
    vCard.uid = '69531f4a-c34d-4a1e-8922-bd38a9476a53';
    vCard.organization = 'ACME Corporation';
     
    //link to image
    vCard.photo.attachFromUrl('https://avatars2.githubusercontent.com/u/5659221?v=3&s=460', 'JPEG');
     
    //or embed image
    vCard.photo.attachFromUrl('/path/to/file.jpeg');
     
    vCard.workPhone = '312-555-1212';
    vCard.birthday = new Date(1985, 0, 1);
    vCard.title = 'Software Developer';
    vCard.url = 'https://github.com/enesser';
    vCard.workUrl = 'https://acme-corporation/enesser';
    vCard.note = 'Notes on Eric';
     
    //set other vitals
    vCard.nickname = 'Scarface';
    vCard.namePrefix = 'Mr.';
    vCard.nameSuffix = 'JR';
    vCard.gender = 'M';
    vCard.anniversary = new Date(2004, 0, 1);
    vCard.role = 'Software Development';
     
    //set other phone numbers
    vCard.homePhone = '312-555-1313';
    vCard.cellPhone = '312-555-1414';
    vCard.pagerPhone = '312-555-1515';
     
    //set fax/facsimile numbers
    vCard.homeFax = '312-555-1616';
    vCard.workFax = '312-555-1717';
     
    //set email addresses
    vCard.email = 'e.nesser@emailhost.tld';
    vCard.workEmail = 'e.nesser@acme-corporation.tld';
     
    //set logo of organization or personal logo (also supports embedding, see above)
    vCard.logo.attachFromUrl('https://avatars2.githubusercontent.com/u/5659221?v=3&s=460', 'JPEG');
     
    //set URL where the vCard can be found
    vCard.source = 'http://mywebpage/myvcard.vcf';
     
    //set address information
    vCard.homeAddress.label = 'Home Address';
    vCard.homeAddress.street = '123 Main Street';
    vCard.homeAddress.city = 'Chicago';
    vCard.homeAddress.stateProvince = 'IL';
    vCard.homeAddress.postalCode = '12345';
    vCard.homeAddress.countryRegion = 'United States of America';
     
    vCard.workAddress.label = 'Work Address';
    vCard.workAddress.street = '123 Corporate Loop\nSuite 500';
    vCard.workAddress.city = 'Los Angeles';
    vCard.workAddress.stateProvince = 'CA';
    vCard.workAddress.postalCode = '54321';
    vCard.workAddress.countryRegion = 'United States of America';
     
    //set social media URLs
    vCard.socialUrls['facebook'] = 'https://...';
    vCard.socialUrls['linkedIn'] = 'https://...';
    vCard.socialUrls['twitter'] = 'https://...';
    vCard.socialUrls['flickr'] = 'https://...';
    vCard.socialUrls['custom'] = 'https://...';
     
    //you can also embed photos from files instead of attaching via URL
    vCard.photo.embedFromFile('photo.jpg');
    vCard.logo.embedFromFile('logo.jpg');
     
    vCard.version = '3.0'; //can also support 2.1 and 4.0, certain versions only support certain fields
     
    //save to file
    vCard.saveToFile('./eric-nesser.vcf');
     
    //get as formatted string
    console.log(vCard.getFormattedString());

    Multiple Email, Fax, & Phone Examples

    email, otherEmail, cellPhone, pagerPhone, homePhone, workPhone, homeFax, workFax, otherPhone all support multiple entries in an array format.

    Examples are provided below:

    var vCardsJS = require('vcards-js');
     
    //create a new vCard
    var vCard = vCardsJS();
     
    //multiple email entry
    vCard.email = [
        'e.nesser@emailhost.tld',
        'e.nesser@emailhost2.tld',
        'e.nesser@emailhost3.tld'
    ];
     
    //multiple cellphone
    vCard.cellPhone = [
        '312-555-1414',
        '312-555-1415',
        '312-555-1416'
    ];
     

    Apple AddressBook Extensions

    You can mark as a contact as an organization with the following Apple AddressBook extension property:

        var vCardsJS = require('vcards-js');
        var vCard = vCardsJS();
        vCard.isOrganization = true;

    React Native

    A React Native version exists here at this repository -- https://github.com/idxbroker/vCards-js/tree/react-native

    Testing

    You can run the vCard unit tests via npm:

    npm test

    Contributions

    Contributions are always welcome!

    Additional thanks to --

    Donations

    BTC 18N1g2o1b9u2jNPbSpGHhV6x5xs6Qou3EV

    License

    Copyright (c) 2014-2019 Eric J Nesser MIT

    Install

    npm i vcards-js

    DownloadsWeekly Downloads

    13,569

    Version

    2.10.0

    License

    MIT

    Unpacked Size

    36.2 kB

    Total Files

    8

    Last publish

    Collaborators

    • enesser