Permissions

Shiny.Contacts uses Shiny.Core’s AccessState permission model — the same model used across every Shiny module — rather than a MAUI-specific permission class. IContactStore exposes two members for working with contact access:

// Request access (triggers the OS prompt if needed)
var access = await contactStore.RequestAccess();

// Check the current state without prompting
var current = contactStore.GetCurrentAccess();

Both return a Shiny.AccessState.

AccessState

State	Meaning
Available	All necessary contact permissions are granted
Denied	The user denied contact access
Restricted	Access is granted in a limited fashion (e.g. read-only or write-only), or restricted by parental controls
Disabled	Contact access has been disabled by the user
NotSetup	A required manifest/Info.plist entry is missing
NotSupported	Contacts are not supported on the current platform
Unknown	Access has not yet been checked, or is in an unknown state

Android

On Android, contact access covers both READ_CONTACTS and WRITE_CONTACTS:

• Available — both read and write access granted
• Restricted — only read or only write granted (not both)
• Denied — neither read nor write granted

Tip

Check for AccessState.Restricted on Android if your app can operate in a read-only or write-only mode.

iOS, Mac Catalyst & macOS

• Available — contacts access authorized
• Denied — contacts access denied
• Restricted — contacts access restricted (e.g. parental controls), or — on iOS 18+ only — limited to the contacts the user picked
• Unknown — not yet determined

Limited access doesn’t exist on Mac Catalyst or macOS, so access there is all-or-nothing.

Every Apple platform needs NSContactsUsageDescription in Info.plist:

<key>NSContactsUsageDescription</key>
<string>This app needs access to your contacts.</string>

Mac Catalyst & sandboxed macOS

The Info.plist key isn’t enough on its own. The App Sandbox — which Mac Catalyst turns on by default — also requires the address book entitlement. Without it, RequestAccess returns Denied and the system prompt never appears.

<ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'maccatalyst'">
    <CustomEntitlements Include="com.apple.security.personal-information.addressbook" Type="Boolean" Value="true" />
</ItemGroup>

Typical Usage Pattern

public class ContactListViewModel(IContactStore contactStore, IDialogs dialogs)
{
    public async Task LoadContacts()
    {
        var access = await contactStore.RequestAccess();
        if (access != AccessState.Available)
        {
            await dialogs.Alert("Permission Required", "Contact access is needed to continue.");
            return;
        }

        var contacts = await contactStore.GetAll();
        // display contacts...
    }
}

Apple Notes & Relations Entitlement

Reading and writing the Note and Relationships properties on iOS requires the com.apple.developer.contacts.notes entitlement. The library probes for access at runtime on every Apple platform, so the same code runs unchanged on Mac Catalyst and macOS.

• If absent: Note returns null and Relationships is empty — no errors
• If present: full read/write access to notes and relations

To enable, add to Entitlements.plist:

<key>com.apple.developer.contacts.notes</key>
<true/>

Caution

This entitlement requires approval from Apple before it can be used in production apps.