whatsapp-float-button

v1.0.0

Published

2 days ago

Floating WhatsApp button for React. Opens a wa.me chat with per-language phone numbers and prefilled messages. Zero runtime dependencies, themeable with CSS variables.

Downloads

125

0High
0Medium
0Low

luismx

whatsapp react floating-button wa.me click-to-chat whatsapp-button widget

whatsapp-float-button

Floating WhatsApp button for React. It renders a circular click-to-chat button anchored to a corner of the viewport and opens https://wa.me/<phone>?text=<message> in a new tab. Runs entirely in the frontend: no backend, no API keys, zero runtime dependencies.

Different phone number and prefilled message per language, with automatic browser-language detection.
Any language tag works (en, es, pt-BR, fr, ...): built-in defaults ship for English and Spanish, everything else is configurable.
No UI/CSS framework dependencies; hand-written CSS (every class prefixed wa- to avoid collisions).
React 18+ as a peer dependency (not bundled).
Theming through --wa-* CSS variables. Looks good with zero configuration.

Install

npm install whatsapp-float-button

react and react-dom (18+) are peer dependencies.

Usage

import { WhatsAppButton } from 'whatsapp-float-button';
import 'whatsapp-float-button/styles.css';

<WhatsAppButton phone="+1 555 010 0140" />;

That is enough: the button shows up bottom-right in WhatsApp green, detects the visitor's language, and opens WhatsApp with a localized default message.

Different phone and message per language

<WhatsAppButton
  phone="+1 555 010 0140"                       // global fallback
  message="Hello! I'd like more information."   // global fallback
  defaultLanguage="en"
  locales={{
    es: {
      phone: '+52 81 1234 5678',
      message: '¡Hola! Quiero más información.',
    },
    'pt-BR': {
      phone: '+55 11 91234 5678',
      message: 'Olá! Gostaria de mais informações.',
      ariaLabel: 'Conversar no WhatsApp',
      tooltip: 'Fale conosco',
    },
  }}
  position="bottom-left"
  showTooltip
  theme={{ primaryColor: '#128c7e' }}
/>;

A Spanish-speaking visitor opens the Mexican number with the Spanish text; a Brazilian visitor opens the Brazilian number with the Portuguese text; everyone else falls back to the global phone and message. Force a specific language with language="es".

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | phone | string | - | WhatsApp number including country code (required). Non-digits are stripped, so "+52 81 1234 5678" is fine. Global fallback when the active language has no override | | message | string | localized default | Prefilled chat text. Pass "" to open WhatsApp without any prefilled text | | ariaLabel | string | localized default | Accessible name of the link | | tooltip | string | localized default | Text of the label bubble next to the button | | showTooltip | boolean | false | Show the localized label bubble | | language | string | autodetected | Explicit language tag; skips browser detection | | defaultLanguage | string | 'en' | Fallback when detection finds nothing usable | | locales | Record<string, WhatsAppLocaleConfig> | - | Per-language phone, message, ariaLabel, tooltip overrides. Keys are case-insensitive | | position | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' | 'bottom-right' | Corner where the button is anchored | | theme | WhatsAppTheme | - | Colors and sizing (see below) |

Language resolution

The active language is resolved in this order:

The language prop, when set.
The first entry of navigator.languages (then navigator.language) that has data — an exact match or a base-subtag match (pt-BR matches pt) in locales or in the built-in strings.
<html lang>, under the same rule.
defaultLanguage (default 'en').

Each field (phone, message, ariaLabel, tooltip) then falls back independently:

locales[language] -> top-level prop -> locales[defaultLanguage] -> built-ins for language -> built-ins for defaultLanguage -> built-in English

Built-in strings ship for en and es. For any other language, provide the texts through locales.

Theming

The theme prop maps to CSS variables. You can also override them directly in CSS:

| Variable | Prop | Default | |----------|------|---------| | --wa-primary | primaryColor | #25d366 | | --wa-primary-contrast | iconColor | #ffffff | | --wa-bg | backgroundColor | #ffffff (tooltip) | | --wa-text | textColor | #1f2937 (tooltip) | | --wa-radius | borderRadius | 999px (tooltip) | | --wa-font | fontFamily | system-ui | | --wa-z | zIndex | 9999 | | --wa-size | size | 56px (button diameter) | | --wa-offset | offset | 24px (distance from the corner) |

All widget classes use the wa- prefix to avoid collisions with host-site CSS.

Utilities

The internals are exported for advanced use:

import { buildWhatsAppUrl, normalizePhone, resolveWhatsAppLink } from 'whatsapp-float-button';

normalizePhone('+52 81 1234 5678');        // '528112345678'
buildWhatsAppUrl('+52 81 1234 5678', 'Hola'); // 'https://wa.me/528112345678?text=Hola'
resolveWhatsAppLink({ phone: '...', locales: { ... } }); // { language, phone, message, ariaLabel, tooltip, url }

SSR

Language autodetection runs in the browser. In server-rendered apps, pass language explicitly to avoid a hydration mismatch between the server and client render.

Trademark

WhatsApp and the WhatsApp logo are trademarks of WhatsApp LLC / Meta. This library is an independent click-to-chat helper and is not affiliated with or endorsed by WhatsApp or Meta.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

whatsapp-float-button

Install

Usage

Different phone and message per language

Props

Language resolution

Theming

Utilities

SSR

Trademark

License