[Tip] vCard Menu Guide

Shortcuts
1

Intro

The Shortcuts app uses different menu styles for Choose from List depending on the type of elements; image menus are displayed in grids, a dictionary or named text items get subtitles, apps or shortcuts have icons, etc.

Contacts also have photos as icons and company names as subtitles. Because they are based on a text format called vCard (https://​en.wikipedia.org/​wiki/​VCard), it’s easy to create custom content-rich menus with them. Here’s how.

img

Format

A vCard can contain many fields but Shortcuts displays only three of them in menus:

BEGIN:VCARD
VERSION:3.0
N:name (title)
ORG:company (optional subtitle)
PHOTO;BASE64:base64 image (optional icon)
END:VCARD

This is the basic structure and no other metadata (encoding, image type, semicolons, etc.) is necessary. VERSION:3.0 ensures that Unicode is displayed correctly. Leading empty lines can break Unicode.

The N field holds multiple optional fields, but we can use just the last name for the menu title without semicolons:

N:Last Name;First Name;Middle Name;Prefix;Suffix

vCard menus can display longer text than text-based menus. They can have multiple lines in the N and ORG fields; more than 30 lines can be shown from N and up to 2 lines from ORG. You can enter \n for line breaks.

Backslashes should be escaped as \\ in all fields. In N and ORG, ; should also be escaped as \;.

img

Icon

Images need to be base64-encoded without line breaks and can be of any standard format such as jpeg, png, gif, bmp, heic, tiff. iPhone displays 93x93 images and iPad uses 62x62 images without scaling. Therefore, 93x93 images will be sufficient for good quality.

img

Tip: You can use SF Symbols to Image (https://​routinehub.co/​shortcut/​19080/) to create vCard icons from 5,000+ SF Symbols.

Presenting menu

After preparing all menu items, you can put them (one or more vCard text) into a single Text action and convert them into Contacts using Set Name to a.vcf → Get Contacts from Input. Then you can add Choose from List.

img

Tip: You can reduce Get Contacts from [Renamed Item] → Choose from [Contacts] into Choose from [Renamed Item as Contact].

Since Chosen Item is a contact, you can get any details (name, company, etc.) from it. You can get the title text from Chosen Item’s name or last name.

Moreover, you can use other fields to hide and get additional info from the chosen item. For example, you can put each item’s index number into NOTE and easily get the index of the chosen item, or use URL to open a link.

More Menu Types

If you want more text but not icons in the menu, there are three more vCard menu types that use emails (EMAIL) or phone numbers (TEL) in different ways.

  • Title + Subtitle + Option using EMAIL
  • Title + Subtitle + Option using TEL
  • Title + Option using EMAIL

img

Here are more details for each type:

BEGIN:VCARD
VERSION:3.0
N:Title
EMAIL;TYPE=Option:Subtitle
END:VCARD

  • T+S+O using EMAIL
    • Title
      • Name of email address
      • Multiline but no line breaks
      • ; should be escaped
    • Subtitle
      • Email address
      • Up to 2 lines
      • Cannot be empty or same as title
    • Option
      • Label of email address
      • Single line
      • ; : should be escaped

BEGIN:VCARD
VERSION:3.0
N:Title
TEL;TYPE=Option:Subtitle
END:VCARD

  • T+S+O using TEL
    • Title
      • Name of Chosen Item
      • Multiline
      • ; should be escaped
    • Subtitle
      • Phone number
      • Up to 2 lines but no line breaks or spaces
      • Only accepts A-Z a-z 0-9 " # + , ; < >
      • Cannot be empty
    • Option
      • Label of phone number
      • Single line
      • ; : should be escaped

BEGIN:VCARD
VERSION:3.0
EMAIL;TYPE=Option:Title
END:VCARD

  • T+O using EMAIL
    • Title
      • Email address
      • Multiline
    • Option
      • Label of email address
      • Single line
      • ; : should be escaped

If you want to use NOTE for hidden info, you need to first find the contact that corresponds to the chosen email/phone using the Filter Contacts action:

img

vCard Menu Editor

You can use vCard Menu Editor (https://​routinehub.co/​shortcut/​19228/) to create vCard menus in any of the four types above, along with menu-building and value-checking actions. It also lets you read existing menus created with the shortcut or List / Choose from Menu actions and edit, reorder, add, delete items or change type, etc.

img

3 Likes
2

I’ve never bothered doing this with shortcuts for my own use but appreciate the guide and would certainly consider doing it if I needed something with images or for someone else. Thank you

1 Like