KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #codex #typescript #cli #deepseek-harness #claude-code #ai-agents #mcp #rust

payload-phone-number-plugin

★ 15 Open GitHub ↗

Phone Number Plugin for Payload CMS

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Payload CMS Phone Number Plugin

[![Payload CMS](https://img.shields.io/badge/Payload%20CMS-v3-blue)](https://github.com/payloadcms/payload)
[![NPM Version](https://img.shields.io/npm/v/payload-phone-number-plugin)](https://www.npmjs.com/package/payload-phone-number-plugin)

This Payload CMS plugin uses [libphonenumber-js](https://www.npmjs.com/package/libphonenumber-js) to format and validate phone numbers.

![Preview](https://raw.githubusercontent.com/adsign/payload-phone-number-plugin/main/src/assets/preview.png)

## Features
- Format phone numbers to multiple formats (E.164, national, international)
- As-you-type formatting based on selected country
- Validates phone numbers based on selected country
- Support for limiting selection to only some countries (per-field or project-wide)
- Support for setting a default country (per-field or project-wide)
- Automatic formatting and region detection when pasting international phone numbers
- Full TypeScript support with generated phone number types
- Built with Payload UI components so it feels native to the Admin Panel
- i18n support for validation messages (PRs for new languages are welcome)

## Installation

Install the `payload-phone-number-plugin` package into your project

```bash
pnpm install payload-phone-number-plugin
```

Add the plugin to your Payload Config:
```ts
import { phoneNumberPlugin } from 'payload-phone-number-plugin';

export const config = buildConfig({
  plugins: [
    phoneNumberPlugin(),
  ]
});
```

Then you can use the phone number field:
```ts
import { phoneNumberField } from 'payload-phone-number-plugin';

const Employees: CollectionConfig = {
  slug: 'employees',
  fields: [
    phoneNumberField({
      name: 'phoneNumber',
      label: 'Phone Number',
      required: true,
    }),
  ]
};
```

> [!NOTE]
> Remember to update your importMap with `generate:importmap` since this plugin adds a custom component

## Plugin Options

| Name                                 | Type                                                            | Required | Description                                                                                                                                       |
| ------------------------------------ | --------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allowedCountries`                   | `RegionCode[]`                                                  | `false`  | Restricts every `phoneNumberField` in the project to these country codes. Individual fields can narrow further but cannot allow countries outside this list. |
| `defaultCountry`                     | `RegionCode`                                                    | `false`  | Project-wide default country. Field-level `defaultCountry` overrides this. Type-narrowed by `allowedCountries`.                                   |
| `admin.cellDisplayFormat`            | `'e164'` \| `'national'` \| `'international'`                   | `false`  | Project-wide default for `admin.cellDisplayFormat`. Field-level value overrides this.                                                             |
| `admin.countryPrefixDisplayFormat`   | `'flagEmoji'` \| `'callingCode'` \| `'flagEmojiAndCallingCode'` | `false`  | Project-wide default for `admin.countryPrefixDisplayFormat`. Field-level value overrides this.                                                    |

### Example: project-wide allowed countries and default

```ts
phoneNumberPlugin({
  allowedCountries: ['NO', 'SE', 'DK', 'US'],
  defaultCountry: 'NO',
})
```

Field-level values override these defaults. `defaultCountry` and field-level `allowedCountries` are constrained to a subset of the plugin's `allowedCountries`.

> [!NOTE]
> Run `payload generate:types` for the type narrowing to take effect.

## Field Props

| Name                              | Type                                                                     | Required | Description                                                                                    | Default                       |
| --------------------------------- | ------------------------------------------------------------------------ | -------- | ---------------------------------------------------------------------------------------------- | ----------------------------- |
| `defaultCountry`                  | `RegionCode`                                                             | `false`  | The default country region code for the field (ISO 3166-1 alpha-2)                             | `'US'`                        |
| `allowedCountries`                | `RegionCode[]`                                                           | `false`  | Array of allowed country codes. If specified, restricts user selection to these countries only |                               |
| `admin.cellDisplayFormat`         | `'e164'` \| `'national'` \| `'international'`                            | `false`  | The format to display phone numbers in table cells                                             | `'international'`             |
| `admin.countryPrefixDisplayFormat`       | `'flagEmoji'` \| `'callingCode'` \| `'flagEmojiAndCallingCode'`          | `false`  | The format to display the country prefix next to the field input                               | `'flagEmojiAndCallingCode'`   |

### Example with Default Country

```ts
phoneNumberField({
  name: 'phoneNumber',
  label: 'Phone Number',
  defaultCountry: 'NO', // Norway will be pre-selected
})
```

### Example with Allowed Countries

```ts
phoneNumberField({
  name: 'phoneNumber',
  label: 'Phone Number',
  allowedCountries: ['NO', 'US', 'SE'], // Only these countries will be selectable
})
```

### Example with Default Country and Allowed Countries

```ts
phoneNumberField({
  name: 'phoneNumber',
  label: 'Phone Number',
  defaultCountry: 'NO', // Norway will be pre-selected
  allowedCountries: ['NO', 'US', 'SE'], // Only these countries will be selectable
})
```

### Example with Cell Display Format

```ts
phoneNumberField({
  name: 'phoneNumber',
  label: 'Phone Number',
  admin: {
    cellDisplayFormat: 'e164', // Display as +4712345678 in table cells
  },
})
```

### Example with Country Prefix Display Format

```ts
phoneNumberField({
  name: 'phoneNumber',
  label: 'Phone Number',
  admin: {
    countryPrefixDisplayFormat: 'callingCode', // Display only +47 (no flag emoji)
  },
})
```

## Creating Documents Programmatically

When creating or updating documents, pass the phone number as an E.164 string directly. Phone numbers are stored in E.164 format in the database.

The field will handle parsing and validation so it won't save unless it's a valid phone number for that field.

### Using the Local API or the Payload REST API SDK
```ts
await payload.create({
  collection: 'employees',
  data: {
    phoneNumber: '+4712345678'
  }
})
```

### Using REST API
```ts
await fetch('http://localhost:3000/api/employees', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    phoneNumber: '+4712345678'
  })
})
```

> [!NOTE]
> You cannot pass a phone number object, only E.164 strings are accepted.

## Querying by Phone Number

When using `payload.find` or database queries, use the E.164 format:

```ts
const employees = await payload.find({
  collection: 'employees',
  where: {
    phoneNumber: {
      equals: '+4712345678'
    }
  }
})
```

The same applies when using the REST API.

## TypeScript Types

The field is typed as `string | PhoneNumber`, similar to Payload's relationship fields with depth.

This is because phone numbers are stored as strings in the database but are transformed into objects when you read them using libphonenumber.

```ts
export interface PhoneNumber {
  e164: string;
  regionCode: string;
  callingCode: string;
  national: string;
  international: string;
}

export interface Employee {
  phoneNumber: string | PhoneNumber;
}
```

Example response:

```json
{
  "phoneNumber": {
    "e164": "+4712345678",
    "regionCode": "NO",
    "callingCode": "+47",
    "national": "12 34 56 78",
    "international": "+47 12 34 56 78"
  }
}
```

## Get the raw phone number value

If you need to access the raw phone number value you can use context when you query:

```ts
const employees = await payload.find({
  collection: 'employees',
  where: {
    phoneNumber: {
      equals: '+4712345678'
    }
  },
  context: {
    phoneNumberPluginReturnRawValue: true,
  },
})
```

Example response:

```json
{
  "phoneNumber": "+4712345678"
}
```

## Additional Information

A region code is an ISO 3166-1 alpha-2 code.

List of all valid region codes can be found here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements

payload-phone-number-plugin

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README