@csauvage/app-store-button

A lightweight React component for rendering App Store, Mac App Store, Apple TV, and TestFlight download badges — with full locale, theme, and QR code support.

On non-Apple devices, the badge automatically switches to a scannable QR code linking to your app.

Features

• 4 store types — App Store, Mac App Store, Apple TV, TestFlight
• 44 locales — from English to Arabic, Japanese, Chinese, and more
• Dark & light themes — matches Apple's official badge styles
• Pure inline SVG — no external CDN, no network requests, works offline
• Device-aware QR codes — shows a QR code on desktop/Android, clickable badge on iPhone/iPad
• TestFlight badges — programmatic SVG generation with full RTL and CJK support
• Zero CSS — inline styles only, no stylesheet to import
• Tree-shakeable — ESM + CJS, ships with TypeScript declarations
• SSR safe — renders the badge by default, hydrates device detection client-side

Install

# npm
npm install @csauvage/app-store-button

# yarn
yarn add @csauvage/app-store-button

# pnpm
pnpm add @csauvage/app-store-button

# bun
bun add @csauvage/app-store-button

Peer dependencies: react >= 18 and react-dom >= 18

Quick Start

import { AppStoreButton, Store, Theme, Locale } from '@csauvage/app-store-button'

function App() {
  return (
    <AppStoreButton
      store={Store.AppStore}
      theme={Theme.Black}
      locale={Locale.EnUs}
      url="https://apps.apple.com/app/id123456789"
      showQrCode
    />
  )
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | store | Store | required | Which store badge to render | | action | Action | Action.Download | Download or pre-order. Ignored for TestFlight | | theme | Theme | Theme.Black | Badge color theme | | locale | Locale | Locale.EnUs | Badge language | | url | string | — | Link URL. Badge becomes clickable when set | | showQrCode | boolean | false | Show QR code on non-Apple devices instead of badge | | height | number | 40 | Badge height in px (width scales proportionally) | | qrSize | number | 120 | QR code size in px (square) | | className | string | — | CSS class on the wrapper element |

Enums

Store

| Value | Description | |-------|-------------| | Store.AppStore | iOS App Store | | Store.MacAppStore | Mac App Store | | Store.AppleTV | Apple TV App Store | | Store.TestFlight | TestFlight beta |

Action

| Value | Description | |-------|-------------| | Action.Download | "Download on the..." | | Action.PreOrder | "Pre-order on the..." |

Theme

| Value | Description | |-------|-------------| | Theme.Black | Dark background, light text | | Theme.White | Light background, dark text |

Locale

44 locales supported:

| Locale | Code | Locale | Code | |--------|------|--------|------| | Locale.EnUs | en-us | Locale.FrFr | fr-fr | | Locale.DeDe | de-de | Locale.EsEs | es-es | | Locale.ItIt | it-it | Locale.PtBr | pt-br | | Locale.Ja | ja | Locale.Ko | ko | | Locale.ZhCn | zh-cn | Locale.ZhTw | zh-tw | | Locale.ArSa | ar-sa | Locale.He | he | | Locale.Ru | ru | Locale.Tr | tr | | Locale.NlNl | nl-nl | Locale.Sv | sv | | Locale.Da | da | Locale.No | no | | Locale.Fi | fi | Locale.Pl | pl |

Az, Id, Ms, Ca, Cs, Da, DeDe, Et, EnUs, EsEs, EsMx, FrFr, FrCa, Hr, ItIt, Lv, Lt, Hu, Mt, NlNl, No, Pl, PtPt, PtBr, Ro, Sk, Sl, Fi, Sv, Tl, Vi, Tr, El, Bg, Ru, Uk, Hi, He, ArSa, Th, Ko, Ja, ZhCn, ZhTw

How It Works

Badge Rendering

All badges are rendered as pure inline SVG — no external CDN requests, no <img> tags, no network dependency. Badges work offline and render instantly.

For App Store, Mac App Store, and Apple TV, the SVG is assembled from pre-extracted vector path data (taken from Apple's official badge SVGs). This includes:

• Apple logo as vector paths (not an image)
• Locale-specific text as vector paths (no font dependency)
• RTL support for Arabic and Hebrew (Apple logo shifts to the right)
• Proper viewBox dimensions per locale

For TestFlight, a localized SVG is generated programmatically since Apple doesn't provide official TestFlight badges. The SVG includes:

• Rounded-rect border matching Apple's badge style
• Embedded TestFlight logo (base64 PNG)
• Localized "Download on" text + "TestFlight" brand name
• RTL support for Arabic and Hebrew (logo flips to right)
• Inverted layout for CJK, Thai, and Hindi (brand name on top)

Device Detection & QR Codes

When showQrCode is enabled:

| Device | Behavior | |--------|----------| | iPhone / iPad | Shows the clickable badge (user can tap to download) | | Desktop / Android | Shows a QR code linking to the URL (user can scan) | | SSR | Renders the badge (safe default, hydrates client-side) |

QR codes are generated using the qrcode library and rendered as inline SVG. The QR code is also wrapped in a clickable link.

Examples

Basic App Store badge

<AppStoreButton store={Store.AppStore} />

French Mac App Store badge with link

<AppStoreButton
  store={Store.MacAppStore}
  locale={Locale.FrFr}
  url="https://apps.apple.com/fr/app/mon-app/id123456789"
/>

Pre-order badge

<AppStoreButton
  store={Store.AppStore}
  action={Action.PreOrder}
  locale={Locale.DeDe}
  url="https://apps.apple.com/de/app/meine-app/id123456789"
/>

TestFlight with light theme

<AppStoreButton
  store={Store.TestFlight}
  theme={Theme.White}
  locale={Locale.Ja}
  url="https://testflight.apple.com/join/abc123"
/>

QR code on desktop, badge on mobile

<AppStoreButton
  store={Store.AppStore}
  url="https://apps.apple.com/app/id123456789"
  showQrCode
  qrSize={150}
/>

Custom height

<AppStoreButton
  store={Store.AppStore}
  height={60}
  url="https://apps.apple.com/app/id123456789"
/>

See the /example folder for a complete working example using Onyria.

License

MIT - Clement Sauvage