/zalo-mini-app

name: zalo-mini-app
description: Build Zalo Mini Apps - lightweight React web apps running inside the Zalo super-app. Use for Zalo Mini App setup, zmp-cli/devtools, ZaUI 1.11.x components, zmp-sdk APIs, permissions, token-based phone number flow, user info, storage, local file storage, camera/media, document preview, payment/Checkout, Open APIs, partner APIs, KYB/eKYC, publication, testing, and Zalo design guidelines.

Zalo Mini App Development

Build Mini Apps for the Zalo platform using React, ZaUI, zmp-sdk, Zalo Mini App CLI/Extension, and platform Open APIs.

Docs baseline: official Zalo Mini App docs checked on **2026-06-24**.

Quick Start

npm install -g zmp-cli
zmp create my-app
cd my-app
zmp start

Core packages:

npm install zmp-ui zmp-sdk

import { App, Page, Button, Input, Modal } from "zmp-ui";
import "zmp-ui/zaui.css";
import { getUserInfo, authorize } from "zmp-sdk/apis";

Current package versions observed on 2026-06-24:

• `zmp-sdk`: 2.51.x
• `zmp-ui`: 1.11.x
• `zmp-cli`: 4.0.x

Always verify package types in the installed project when implementing exact props or SDK return types.

References

Setup & Release

• [getting-started.md](./references/getting-started.md) - Create app, auth, permissions, CLI/Extension, test, publish
• [design-guidelines.md](./references/design-guidelines.md) - Zalo design standards and review checklist
• [web-design-guidelines.md](./references/web-design-guidelines.md) - Accessibility, mobile UX, forms, performance
• [react-best-practices.md](./references/react-best-practices.md) - Waterfalls, bundle size, re-renders, JS performance

SDK APIs

• [api-overview.md](./references/api-overview.md) - API groups, import patterns, error handling
• [api-user.md](./references/api-user.md) - authorize, getUserInfo, token-based getPhoneNumber, getAccessToken
• [api-storage.md](./references/api-storage.md) - Storage APIs and legacy aliases
• [api-ui.md](./references/api-ui.md) - toast, navigation bar, webview, routing
• [api-device.md](./references/api-device.md) - location, camera, media picker, document, QR/NFC, network
• [api-local-file-storage.md](./references/api-local-file-storage.md) - Local File Storage APIs
• [api-permission-biometric.md](./references/api-permission-biometric.md) - permissions and biometric auth
• [api-advertising-widgets.md](./references/api-advertising-widgets.md) - ads and function/OA widgets
• [api-zalo.md](./references/api-zalo.md) - OA, chat, sharing, profile, shortcuts

Payment / Backend APIs

• [payment-checkout.md](./references/payment-checkout.md) - Payment integration, order, callback, status, refund
• [open-apis.md](./references/open-apis.md) - Open APIs, partner APIs, signature verification, KYB notes
• [ekyc-apis.md](./references/ekyc-apis.md) - eKYC API map and secure integration notes

ZaUI Components

• [zaui-overview.md](./references/zaui-overview.md) - Component list and design tokens
• [zaui-layout.md](./references/zaui-layout.md) - App, Page, Header, Router, BottomNavigation, Box utilities
• [zaui-display.md](./references/zaui-display.md) - Avatar, Icon, List, Swiper, Calendar, Text
• [zaui-form.md](./references/zaui-form.md) - Button, Input, Select, DatePicker, OTP, Slider
• [zaui-overlay.md](./references/zaui-overlay.md) - Modal, Sheet, ActionSheet, SnackbarProvider

Critical Current Patterns

Phone Number: Token Flow, Not Direct Number

import { getPhoneNumber } from "zmp-sdk/apis";

const { token } = await getPhoneNumber({});
// Send token to backend immediately.
// Backend exchanges token with Zalo Open API to get the actual phone number.
// Token is single-use and short-lived.

Do **not** expect `getPhoneNumber` to return `{ number }` in current docs.

Location: Token Flow, Not Direct Coordinates

import { getLocation } from "zmp-sdk/apis";

const { token } = await getLocation();
// Send token to backend for Zalo Open API exchange.

Do **not** expect `getLocation` to return direct `{ latitude, longitude }` in current docs.

Local File Storage: LFSStorage Namespace

import { LFSStorage } from "zmp-sdk/apis";

const { support } = await LFSStorage.isSupportLFS();
const { savedPath } = await LFSStorage.saveFile({ filePath: "local-temp-path" });

Use `filePath` / `savedPath`, not old `tempFilePath` helpers.

Media Picker: Current Shape

import { openMediaPicker } from "zmp-sdk/apis";

const { data } = await openMediaPicker({
  type: "photo",
  maxSelectItem: 5,
  serverUploadUrl: "https://example.com/upload"
});

Use `maxSelectItem`, not `maxSelection`.

Basic Page Layout

import { App, Page, Header, List, Icon, BottomNavigation } from "zmp-ui";

export default function Root() {
  return (
    <App>
      <Page>
        <Header title="Home" />
        <List>
          <List.Item title="Item" suffix={<Icon icon="zi-chevron-right" />} />
        </List>
      </Page>
      <BottomNavigation fixed>
        <BottomNavigation.Item key="home" label="Home" icon={<Icon icon="zi-home" />} />
      </BottomNavigation>
    </App>
  );
}

Resources

• Docs: https://miniapp.zaloplatforms.com/documents/
• API: https://miniapp.zaloplatforms.com/documents/api/
• ZaUI: https://miniapp.zaloplatforms.com/documents/zaui/
• Payment: https://miniapp.zaloplatforms.com/documents/payment/
• Open APIs: https://miniapp.zaloplatforms.com/documents/open-apis/
• Mini App Center: https://miniapp.zaloplatforms.com/