telpick

v2.0.6

Published

20 days ago

Multi-platform country and phone code selector with a modern design, smooth animations, and automatic IP detection.

0High
0Medium
0Low

country phone selector country-selector phone-code dial-code vue react vanilla cdn telpick geolocation ip-detection typescript

Telpick

Multi-platform country and phone code selector with a modern design, smooth animations, and automatic IP detection.

English | Español

Try the demo

You can try the interactive demo online:

→ Open demo (GitHub Pages)

Features

Modern design with smooth animations
Automatic country detection by IP (multiple fallback services)
Compatible with Vue 3, React, and Vanilla JavaScript
Customizable via CSS variables
Accessible with ARIA attributes
Responsive design
Built-in country search
Lightweight with no heavy dependencies

Installation

npm

npm install telpick

pnpm

pnpm add telpick

yarn

yarn add telpick

CDN

<link rel="stylesheet" href="https://unpkg.com/telpick@latest/dist/style.css">
<script src="https://unpkg.com/telpick@latest/dist/telpick.umd.js"></script>

Importing CSS: Use import 'telpick/dist/style.css' when you install from npm (the published package includes dist). If you install from GitHub (e.g. npm install github:julioalmirooficial/telpick), use import 'telpick/src/telpick.css' instead, because dist is not in the repo.

Usage

React

import React, { useState } from 'react'
import { TelpickReact } from 'telpick/react'
import 'telpick/dist/style.css'

function App() {
  const [selectedCountry, setSelectedCountry] = useState(null)

  return (
    <TelpickReact
      code={null}
      onChange={(country) => {
        console.log('Selected country:', country)
        setSelectedCountry(country)
      }}
    />
  )
}

Vue 3

<template>
  <TelpickVue
    :code="selectedCode"
    @update:code="handleCountryChange"
  />
</template>

<script setup>
import { ref } from 'vue'
import { TelpickVue } from 'telpick/vue'
import 'telpick/dist/style.css'

const selectedCode = ref(null)

const handleCountryChange = (country) => {
  console.log('Selected country:', country)
  selectedCode.value = country.country_code
}
</script>

Vanilla JavaScript

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://unpkg.com/telpick@latest/dist/style.css">
</head>
<body>
  <div id="telpick-container"></div>
  
  <script src="https://unpkg.com/telpick@latest/dist/telpick.umd.js"></script>
  <script>
    const telpick = new Telpick({
      code: null,
      onChange: (country) => {
        console.log('Selected country:', country)
      }
    })
    telpick.init(document.getElementById('telpick-container'))
  </script>
</body>
</html>

Props

`code` (optional)

Initial country code (ISO 3166-1 alpha-2). If null, it is detected automatically by IP.

Type: string | null
Default: null

<TelpickReact code="ES" onChange={handleChange} />

`onChange` (optional)

Callback fired when the user selects a country.

Type: (country: CountryCode) => void

<TelpickReact
  onChange={(country) => {
    console.log('Code:', country.code)
    console.log('Country:', country.country)
    console.log('Flag:', country.flag)
    console.log('ISO code:', country.country_code)
  }}
/>

`styleOverrides` (optional)

Object of inline CSS styles to customize the main button.

Type: Partial<Record<string, string>>

<TelpickReact
  styleOverrides={{
    padding: '12px 16px',
    fontSize: '16px',
    backgroundColor: '#f0f0f0'
  }}
/>

Customization

You can customize styles using CSS variables:

:root {
  --telpick-bg: #ffffff;
  --telpick-border: #e5e7eb;
  --telpick-radius: 12px;
  --telpick-flag-size: 24px;
  --telpick-font-size: 14px;
  --telpick-selected-bg: #eff6ff;
  --telpick-selected-border: #3b82f6;
  --telpick-selected-shadow: 2px 0 4px rgba(59, 130, 246, 0.3);
  --telpick-selected-text: #1f2937;
  --telpick-text: #1f2937;
  --telpick-text-secondary: #6b7280;
  --telpick-border-focus: #3b82f6;
  --telpick-transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
  --telpick-font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
}

CountryCode interface

interface CountryCode {
  country_code: string  // ISO 3166-1 alpha-2 code (e.g. "ES", "US")
  flag: string          // Country flag URL
  country: string       // Country name (e.g. "Spain", "United States")
  code: string         // Phone code (e.g. "+34", "+1")
}

License

MIT

Created by

Julio Almiro

Donate

If this project has been useful to you, consider donating to support its development and maintenance.