whatsapp-float-button 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +129 -0
  2. package/dist/index.d.ts +95 -0
  3. package/dist/index.js +124 -0
  4. package/dist/styles.css +1 -0
  5. package/package.json +65 -0
package/README.md ADDED
@@ -0,0 +1,129 @@
1
+ # whatsapp-float-button
2
+
3
+ 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.
4
+
5
+ - Different phone number and prefilled message **per language**, with automatic browser-language detection.
6
+ - Any language tag works (`en`, `es`, `pt-BR`, `fr`, ...): built-in defaults ship for English and Spanish, everything else is configurable.
7
+ - No UI/CSS framework dependencies; hand-written CSS (every class prefixed `wa-` to avoid collisions).
8
+ - React 18+ as a peer dependency (not bundled).
9
+ - Theming through `--wa-*` CSS variables. Looks good with zero configuration.
10
+
11
+ ## Install
12
+
13
+ ```sh
14
+ npm install whatsapp-float-button
15
+ ```
16
+
17
+ `react` and `react-dom` (18+) are peer dependencies.
18
+
19
+ ## Usage
20
+
21
+ ```tsx
22
+ import { WhatsAppButton } from 'whatsapp-float-button';
23
+ import 'whatsapp-float-button/styles.css';
24
+
25
+ <WhatsAppButton phone="+1 555 010 0140" />;
26
+ ```
27
+
28
+ 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.
29
+
30
+ ### Different phone and message per language
31
+
32
+ ```tsx
33
+ <WhatsAppButton
34
+ phone="+1 555 010 0140" // global fallback
35
+ message="Hello! I'd like more information." // global fallback
36
+ defaultLanguage="en"
37
+ locales={{
38
+ es: {
39
+ phone: '+52 81 1234 5678',
40
+ message: '¡Hola! Quiero más información.',
41
+ },
42
+ 'pt-BR': {
43
+ phone: '+55 11 91234 5678',
44
+ message: 'Olá! Gostaria de mais informações.',
45
+ ariaLabel: 'Conversar no WhatsApp',
46
+ tooltip: 'Fale conosco',
47
+ },
48
+ }}
49
+ position="bottom-left"
50
+ showTooltip
51
+ theme={{ primaryColor: '#128c7e' }}
52
+ />;
53
+ ```
54
+
55
+ 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"`.
56
+
57
+ ## Props
58
+
59
+ | Prop | Type | Default | Description |
60
+ |------|------|---------|-------------|
61
+ | `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 |
62
+ | `message` | `string` | localized default | Prefilled chat text. Pass `""` to open WhatsApp without any prefilled text |
63
+ | `ariaLabel` | `string` | localized default | Accessible name of the link |
64
+ | `tooltip` | `string` | localized default | Text of the label bubble next to the button |
65
+ | `showTooltip` | `boolean` | `false` | Show the localized label bubble |
66
+ | `language` | `string` | autodetected | Explicit language tag; skips browser detection |
67
+ | `defaultLanguage` | `string` | `'en'` | Fallback when detection finds nothing usable |
68
+ | `locales` | `Record<string, WhatsAppLocaleConfig>` | - | Per-language `phone`, `message`, `ariaLabel`, `tooltip` overrides. Keys are case-insensitive |
69
+ | `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Corner where the button is anchored |
70
+ | `theme` | `WhatsAppTheme` | - | Colors and sizing (see below) |
71
+
72
+ ## Language resolution
73
+
74
+ The active language is resolved in this order:
75
+
76
+ 1. The `language` prop, when set.
77
+ 2. 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.
78
+ 3. `<html lang>`, under the same rule.
79
+ 4. `defaultLanguage` (default `'en'`).
80
+
81
+ Each field (`phone`, `message`, `ariaLabel`, `tooltip`) then falls back independently:
82
+
83
+ ```txt
84
+ locales[language] -> top-level prop -> locales[defaultLanguage] -> built-ins for language -> built-ins for defaultLanguage -> built-in English
85
+ ```
86
+
87
+ Built-in strings ship for `en` and `es`. For any other language, provide the texts through `locales`.
88
+
89
+ ## Theming
90
+
91
+ The `theme` prop maps to CSS variables. You can also override them directly in CSS:
92
+
93
+ | Variable | Prop | Default |
94
+ |----------|------|---------|
95
+ | `--wa-primary` | `primaryColor` | `#25d366` |
96
+ | `--wa-primary-contrast` | `iconColor` | `#ffffff` |
97
+ | `--wa-bg` | `backgroundColor` | `#ffffff` (tooltip) |
98
+ | `--wa-text` | `textColor` | `#1f2937` (tooltip) |
99
+ | `--wa-radius` | `borderRadius` | `999px` (tooltip) |
100
+ | `--wa-font` | `fontFamily` | system-ui |
101
+ | `--wa-z` | `zIndex` | `9999` |
102
+ | `--wa-size` | `size` | `56px` (button diameter) |
103
+ | `--wa-offset` | `offset` | `24px` (distance from the corner) |
104
+
105
+ All widget classes use the `wa-` prefix to avoid collisions with host-site CSS.
106
+
107
+ ## Utilities
108
+
109
+ The internals are exported for advanced use:
110
+
111
+ ```ts
112
+ import { buildWhatsAppUrl, normalizePhone, resolveWhatsAppLink } from 'whatsapp-float-button';
113
+
114
+ normalizePhone('+52 81 1234 5678'); // '528112345678'
115
+ buildWhatsAppUrl('+52 81 1234 5678', 'Hola'); // 'https://wa.me/528112345678?text=Hola'
116
+ resolveWhatsAppLink({ phone: '...', locales: { ... } }); // { language, phone, message, ariaLabel, tooltip, url }
117
+ ```
118
+
119
+ ## SSR
120
+
121
+ Language autodetection runs in the browser. In server-rendered apps, pass `language` explicitly to avoid a hydration mismatch between the server and client render.
122
+
123
+ ## Trademark
124
+
125
+ 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.
126
+
127
+ ## License
128
+
129
+ UNLICENSED — all rights reserved.
package/dist/index.d.ts ADDED
@@ -0,0 +1,95 @@
1
+ import { JSX as JSX_2 } from 'react';
2
+
3
+ /**
4
+ * Builds a wa.me click-to-chat URL. The phone must include the country code
5
+ * (wa.me requirement). An empty or undefined message omits the ?text= param.
6
+ */
7
+ export declare function buildWhatsAppUrl(phone: string, message?: string): string;
8
+
9
+ /** Strips everything but digits: "+52 (81) 1234-5678" -> "528112345678". */
10
+ export declare function normalizePhone(phone: string): string;
11
+
12
+ /** Result of resolving language + config into a final wa.me link. */
13
+ export declare interface ResolvedWhatsAppLink {
14
+ language: string;
15
+ /** Normalized digits, ready for wa.me. */
16
+ phone: string;
17
+ message?: string;
18
+ ariaLabel: string;
19
+ tooltip?: string;
20
+ url: string;
21
+ }
22
+
23
+ /**
24
+ * Resolves the active language and merges per-language config into the final
25
+ * link. Merge order per field: locales[language] -> top-level prop ->
26
+ * locales[defaultLanguage] -> built-ins for language -> built-ins for
27
+ * defaultLanguage -> built-in English.
28
+ */
29
+ export declare function resolveWhatsAppLink(props: WhatsAppButtonProps): ResolvedWhatsAppLink;
30
+
31
+ export declare function WhatsAppButton(props: WhatsAppButtonProps): JSX_2.Element;
32
+
33
+ export declare interface WhatsAppButtonProps {
34
+ /**
35
+ * Full international number including country code; non-digits are stripped
36
+ * ("+52 81 1234 5678" is fine). Global fallback when the active language has no override.
37
+ */
38
+ phone: string;
39
+ /** Prefilled message fallback. Empty string '' disables the ?text= param. */
40
+ message?: string;
41
+ /** Accessible label fallback for the link. */
42
+ ariaLabel?: string;
43
+ /** Tooltip text fallback (shown only when showTooltip is true). */
44
+ tooltip?: string;
45
+ /** Show the small localized label bubble next to the button. Default false. */
46
+ showTooltip?: boolean;
47
+ /** Explicit language; skips browser autodetection. Any tag, e.g. 'pt-BR'. */
48
+ language?: string;
49
+ /** Fallback when detection finds nothing usable. Default 'en'. */
50
+ defaultLanguage?: string;
51
+ /** Per-language phone/message/label overrides. */
52
+ locales?: Record<string, WhatsAppLocaleConfig>;
53
+ /** Corner where the button is anchored. Default 'bottom-right'. */
54
+ position?: WhatsAppPosition;
55
+ theme?: WhatsAppTheme;
56
+ }
57
+
58
+ /** Per-language overrides. Any BCP-47-ish tag as key ('en', 'es', 'pt-BR', ...). */
59
+ export declare interface WhatsAppLocaleConfig {
60
+ /** WhatsApp number for this language. Falls back to the top-level phone. */
61
+ phone?: string;
62
+ /** Prefilled message for this language. Empty string '' disables the ?text= param. */
63
+ message?: string;
64
+ /** Accessible label for the link in this language. */
65
+ ariaLabel?: string;
66
+ /** Tooltip text for this language (shown only when showTooltip is true). */
67
+ tooltip?: string;
68
+ }
69
+
70
+ /** Corner where the floating button is anchored. */
71
+ export declare type WhatsAppPosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
72
+
73
+ /** Maps to --wa-* CSS variables; styles live in whatsapp.css. */
74
+ export declare interface WhatsAppTheme {
75
+ /** Button background. Default WhatsApp green #25D366. Maps to --wa-primary. */
76
+ primaryColor?: string;
77
+ /** Glyph color inside the button. Maps to --wa-primary-contrast. */
78
+ iconColor?: string;
79
+ /** Tooltip background. Maps to --wa-bg. */
80
+ backgroundColor?: string;
81
+ /** Tooltip text color. Maps to --wa-text. */
82
+ textColor?: string;
83
+ /** Tooltip corner radius. Maps to --wa-radius. */
84
+ borderRadius?: string;
85
+ /** Maps to --wa-font. */
86
+ fontFamily?: string;
87
+ /** Maps to --wa-z. */
88
+ zIndex?: number;
89
+ /** Button diameter, default 56px. Maps to --wa-size. */
90
+ size?: string;
91
+ /** Distance from the viewport corner, default 24px. Maps to --wa-offset. */
92
+ offset?: string;
93
+ }
94
+
95
+ export { }
package/dist/index.js ADDED
@@ -0,0 +1,124 @@
1
+ import { jsx as l, jsxs as m } from "react/jsx-runtime";
2
+ import { useMemo as C } from "react";
3
+ const c = {
4
+ en: {
5
+ ariaLabel: "Chat on WhatsApp",
6
+ message: "Hello! I'd like more information.",
7
+ tooltip: "Chat with us"
8
+ },
9
+ es: {
10
+ ariaLabel: "Chatear por WhatsApp",
11
+ message: "¡Hola! Me gustaría más información.",
12
+ tooltip: "Escríbenos"
13
+ }
14
+ };
15
+ function b(o) {
16
+ return o.replace(/\D/g, "");
17
+ }
18
+ function L(o, a) {
19
+ const n = b(o);
20
+ n.length === 0 && console.warn(`[whatsapp-float-button] phone "${o}" has no digits; the wa.me link will not work.`);
21
+ const t = `https://wa.me/${n}`;
22
+ return a ? `${t}?text=${encodeURIComponent(a)}` : t;
23
+ }
24
+ function p(o) {
25
+ return o.split("-")[0];
26
+ }
27
+ function v(o = {}) {
28
+ const a = {};
29
+ for (const [n, t] of Object.entries(o))
30
+ a[n.toLowerCase()] = t;
31
+ return a;
32
+ }
33
+ function w(o, a, n) {
34
+ var t, r;
35
+ return ((t = o[a]) == null ? void 0 : t[n]) ?? ((r = o[p(a)]) == null ? void 0 : r[n]);
36
+ }
37
+ function h(o, a) {
38
+ var n, t;
39
+ return ((n = c[o]) == null ? void 0 : n[a]) ?? ((t = c[p(o)]) == null ? void 0 : t[a]);
40
+ }
41
+ function y(o) {
42
+ const a = [];
43
+ typeof navigator < "u" && a.push(...navigator.languages ?? [navigator.language]), typeof document < "u" && a.push(document.documentElement.lang);
44
+ for (const n of a) {
45
+ if (!n) continue;
46
+ const t = n.toLowerCase();
47
+ if (o(t)) return t;
48
+ if (o(p(t))) return p(t);
49
+ }
50
+ }
51
+ function x(o) {
52
+ var g;
53
+ const a = v(o.locales), n = (o.defaultLanguage ?? "en").toLowerCase(), t = (e) => e in a || e in c, r = ((g = o.language) == null ? void 0 : g.toLowerCase()) ?? y(t) ?? n, i = (e) => [
54
+ w(a, r, e),
55
+ o[e],
56
+ w(a, n, e),
57
+ h(r, e),
58
+ h(n, e),
59
+ c.en[e]
60
+ ], s = i("message").find((e) => e !== void 0), u = i("tooltip").find((e) => e !== void 0), f = i("ariaLabel").find((e) => e) ?? c.en.ariaLabel, d = w(a, r, "phone") || o.phone;
61
+ return {
62
+ language: r,
63
+ phone: b(d),
64
+ message: s,
65
+ ariaLabel: f,
66
+ tooltip: u,
67
+ url: L(d, s)
68
+ };
69
+ }
70
+ function k() {
71
+ return /* @__PURE__ */ l(
72
+ "svg",
73
+ {
74
+ viewBox: "0 0 24 24",
75
+ width: "28",
76
+ height: "28",
77
+ fill: "currentColor",
78
+ "aria-hidden": "true",
79
+ focusable: "false",
80
+ children: /* @__PURE__ */ l("path", { d: "M17.472 14.382c-.297-.149-1.758-.867-2.03-.967-.273-.099-.471-.148-.67.15-.197.297-.767.966-.94 1.164-.173.199-.347.223-.644.075-.297-.15-1.255-.463-2.39-1.475-.883-.788-1.48-1.761-1.653-2.059-.173-.297-.018-.458.13-.606.134-.133.298-.347.446-.52.149-.174.198-.298.298-.497.099-.198.05-.371-.025-.52-.075-.149-.669-1.612-.916-2.207-.242-.579-.487-.5-.669-.51-.173-.008-.371-.01-.57-.01-.198 0-.52.074-.792.372-.272.297-1.04 1.016-1.04 2.479 0 1.462 1.065 2.875 1.213 3.074.149.198 2.096 3.2 5.077 4.487.709.306 1.262.489 1.694.625.712.227 1.36.195 1.871.118.571-.085 1.758-.719 2.006-1.413.248-.694.248-1.289.173-1.413-.074-.124-.272-.198-.57-.347m-5.421 7.403h-.004a9.87 9.87 0 0 1-5.031-1.378l-.361-.214-3.741.982.998-3.648-.235-.374a9.86 9.86 0 0 1-1.51-5.26c.001-5.45 4.436-9.884 9.888-9.884 2.64 0 5.122 1.03 6.988 2.898a9.825 9.825 0 0 1 2.893 6.994c-.003 5.45-4.437 9.884-9.885 9.884m8.413-18.297A11.815 11.815 0 0 0 12.05 0C5.495 0 .16 5.335.157 11.892c0 2.096.547 4.142 1.588 5.945L.057 24l6.305-1.654a11.882 11.882 0 0 0 5.683 1.448h.005c6.554 0 11.89-5.335 11.893-11.893a11.821 11.821 0 0 0-3.48-8.413Z" })
81
+ }
82
+ );
83
+ }
84
+ function z(o = {}) {
85
+ const a = {};
86
+ return o.primaryColor && (a["--wa-primary"] = o.primaryColor), o.iconColor && (a["--wa-primary-contrast"] = o.iconColor), o.backgroundColor && (a["--wa-bg"] = o.backgroundColor), o.textColor && (a["--wa-text"] = o.textColor), o.borderRadius && (a["--wa-radius"] = o.borderRadius), o.fontFamily && (a["--wa-font"] = o.fontFamily), o.zIndex !== void 0 && (a["--wa-z"] = String(o.zIndex)), o.size && (a["--wa-size"] = o.size), o.offset && (a["--wa-offset"] = o.offset), a;
87
+ }
88
+ function W(o) {
89
+ const {
90
+ phone: a,
91
+ message: n,
92
+ ariaLabel: t,
93
+ tooltip: r,
94
+ showTooltip: i = !1,
95
+ language: s,
96
+ defaultLanguage: u,
97
+ locales: f,
98
+ position: d = "bottom-right",
99
+ theme: g
100
+ } = o, e = C(
101
+ () => x({ phone: a, message: n, ariaLabel: t, tooltip: r, language: s, defaultLanguage: u, locales: f }),
102
+ [a, n, t, r, s, u, f]
103
+ );
104
+ return /* @__PURE__ */ m("div", { className: `wa-widget wa-widget--${d}`, style: z(g), children: [
105
+ i && e.tooltip && /* @__PURE__ */ l("span", { className: "wa-tooltip", "aria-hidden": "true", children: e.tooltip }),
106
+ /* @__PURE__ */ l(
107
+ "a",
108
+ {
109
+ className: "wa-launcher",
110
+ href: e.url,
111
+ target: "_blank",
112
+ rel: "noopener noreferrer",
113
+ "aria-label": e.ariaLabel,
114
+ children: /* @__PURE__ */ l(k, {})
115
+ }
116
+ )
117
+ ] });
118
+ }
119
+ export {
120
+ W as WhatsAppButton,
121
+ L as buildWhatsAppUrl,
122
+ b as normalizePhone,
123
+ x as resolveWhatsAppLink
124
+ };
package/dist/styles.css ADDED
@@ -0,0 +1 @@
1
+ .wa-widget{--wa-primary: #25d366;--wa-primary-contrast: #ffffff;--wa-bg: #ffffff;--wa-text: #1f2937;--wa-radius: 999px;--wa-font: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;--wa-z: 9999;--wa-shadow: 0 6px 20px rgba(0, 0, 0, .22);--wa-offset: 24px;--wa-size: 56px;position:fixed;display:flex;align-items:center;gap:12px;z-index:var(--wa-z);font-family:var(--wa-font);color:var(--wa-text);line-height:1.45}.wa-widget *,.wa-widget *:before,.wa-widget *:after{box-sizing:border-box}.wa-widget--bottom-right{bottom:var(--wa-offset);right:var(--wa-offset);flex-direction:row}.wa-widget--bottom-left{bottom:var(--wa-offset);left:var(--wa-offset);flex-direction:row-reverse}.wa-widget--top-right{top:var(--wa-offset);right:var(--wa-offset);flex-direction:row}.wa-widget--top-left{top:var(--wa-offset);left:var(--wa-offset);flex-direction:row-reverse}.wa-launcher{display:flex;align-items:center;justify-content:center;width:var(--wa-size);height:var(--wa-size);border:none;border-radius:50%;background:var(--wa-primary);color:var(--wa-primary-contrast);cursor:pointer;text-decoration:none;box-shadow:var(--wa-shadow);transition:transform .15s ease,box-shadow .15s ease}.wa-launcher:hover{transform:scale(1.06);box-shadow:0 8px 26px #00000042}.wa-launcher:active{transform:scale(.97)}.wa-launcher:focus-visible{outline:3px solid var(--wa-primary);outline-offset:3px}.wa-tooltip{padding:8px 14px;background:var(--wa-bg);color:var(--wa-text);border-radius:var(--wa-radius);font-size:14px;white-space:nowrap;box-shadow:0 4px 14px #0000001f;animation:wa-fade-in .18s ease-out}@keyframes wa-fade-in{0%{opacity:0;transform:translateY(4px)}to{opacity:1;transform:translateY(0)}}@media(max-width:480px){.wa-widget{--wa-offset: 16px}}@media(prefers-reduced-motion:reduce){.wa-tooltip{animation:none}.wa-launcher,.wa-launcher:hover,.wa-launcher:active{transform:none;transition:none}}
package/package.json ADDED
@@ -0,0 +1,65 @@
1
+ {
2
+ "name": "whatsapp-float-button",
3
+ "version": "1.0.0",
4
+ "description": "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.",
5
+ "keywords": [
6
+ "whatsapp",
7
+ "react",
8
+ "floating-button",
9
+ "wa.me",
10
+ "click-to-chat",
11
+ "whatsapp-button",
12
+ "widget"
13
+ ],
14
+ "license": "UNLICENSED",
15
+ "repository": {
16
+ "type": "git",
17
+ "url": "git+https://github.com/chimney45/whatsapp-float-button.git"
18
+ },
19
+ "type": "module",
20
+ "files": [
21
+ "dist"
22
+ ],
23
+ "main": "./dist/index.js",
24
+ "module": "./dist/index.js",
25
+ "types": "./dist/index.d.ts",
26
+ "exports": {
27
+ ".": {
28
+ "types": "./dist/index.d.ts",
29
+ "import": "./dist/index.js"
30
+ },
31
+ "./styles.css": "./dist/styles.css"
32
+ },
33
+ "sideEffects": [
34
+ "**/*.css"
35
+ ],
36
+ "scripts": {
37
+ "dev": "vite",
38
+ "build": "tsc -p tsconfig.json --noEmit && vite build",
39
+ "build:dev": "tsc -p tsconfig.json --noEmit && vite build --config vite.demo.config.ts",
40
+ "test": "vitest run",
41
+ "test:watch": "vitest",
42
+ "lint": "eslint src dev"
43
+ },
44
+ "peerDependencies": {
45
+ "react": ">=18",
46
+ "react-dom": ">=18"
47
+ },
48
+ "devDependencies": {
49
+ "@testing-library/react": "^16.1.0",
50
+ "@types/node": "^25.9.2",
51
+ "@types/react": "^18.3.12",
52
+ "@types/react-dom": "^18.3.1",
53
+ "@vitejs/plugin-react": "^4.3.4",
54
+ "eslint": "^9.17.0",
55
+ "eslint-plugin-react-hooks": "^5.1.0",
56
+ "jsdom": "^25.0.1",
57
+ "react": "^18.3.1",
58
+ "react-dom": "^18.3.1",
59
+ "typescript": "^5.7.2",
60
+ "typescript-eslint": "^8.18.0",
61
+ "vite": "^6.0.3",
62
+ "vite-plugin-dts": "^4.3.0",
63
+ "vitest": "^3.2.6"
64
+ }
65
+ }