A modern, single-file subscription page for 3X-UI — usage ring, live status, dark/light themes, Persian + English, and one-tap import into VPN clients.
No CDN. No build step. No binary patching. One index.html.
bash <(curl -Ls https://raw.githubusercontent.com/ehsanh4/3x-ui-theme/main/install.sh)That's it. The installer copies the template to /usr/local/x-ui/sub_theme/, points the panel's Sub Theme Directory at it, and restarts x-ui.
Then open any subscription URL in a browser.
# Copy the template only — set the path yourself in the panel
bash <(curl -Ls https://raw.githubusercontent.com/ehsanh4/3x-ui-theme/main/install.sh) --no-db
# Don't restart x-ui at the end
bash <(curl -Ls https://raw.githubusercontent.com/ehsanh4/3x-ui-theme/main/install.sh) --no-restart
# Remove it and go back to the built-in page
bash <(curl -Ls https://raw.githubusercontent.com/ehsanh4/3x-ui-theme/main/install.sh) --uninstall- Copy
index.htmlto a folder on the server, e.g./usr/local/x-ui/sub_theme/ - In the panel: Settings → Subscription → Information → Sub Theme Directory → set the absolute path to that folder
- Save, then run
x-ui restart
The installer backs up x-ui.db before touching it, and backs up any template already in the target folder.
| Usage ring | Animated SVG gauge with percentage used, ∞ for unlimited plans |
| Live status | Active/inactive + online/offline chip, auto-refreshing every 30s |
| Expiry | Days remaining with colour warnings (amber ≤ 7 days, red ≤ 3), Jalali or Gregorian dates |
| Traffic stats | Total, download, upload, remaining |
| One-tap import | Deep links for Hiddify, Happ, v2Box, v2rayNG, Streisand — filtered to the visitor's OS |
| Subscription links | Base64, JSON and Clash/Mihomo links with copy buttons and a QR code |
| Config list | Per-config rows with protocol badges and individual copy buttons |
| Bilingual | Persian (RTL) and English (LTR), auto-detected, switchable, saved |
| Dark / light | Follows the OS by default, toggle in the header, saved |
| Announcements | Renders the panel's announcement field with an animated glowing border |
| Airgap-safe | QR generator is inlined — the page needs no outbound network |
Everything you'd normally want to change sits in one CONFIG block near the top of index.html:
const CONFIG = {
brandName: "پنل اشتراک", // fallback title when the panel's Sub Title is empty
supportFallback: "", // support URL when the panel doesn't provide one
defaultLang: "auto", // "auto" | "fa" | "en"
apps: [ ... ] // client apps and their deep-link schemes
};Add an entry to CONFIG.apps:
{ name:"MyApp", plat:"iOS/Android", os:["ios","android"], scheme:"myapp://import?url={URL_ENC}" }| Placeholder | Replaced with |
|---|---|
{URL} |
the raw subscription URL |
{URL_ENC} |
URL-encoded subscription URL |
{URL_B64} |
base64-encoded subscription URL |
{NAME_ENC} |
URL-encoded subscription title |
os controls which apps show by default — the page detects the visitor's platform and hides the rest behind a "show all" button. Valid values: android, ios, windows, macos, linux.
The palette lives in two CSS blocks, :root (dark) and :root[data-theme="light"]. The accents are --accent and --accent-2; changing those two restyles the gauge, buttons, glow borders and links together.
All strings are in the I18N object — en and fa. Edit in place, or add a language by copying a block and extending the .lang-toggle buttons.
- 3X-UI with subscriptions enabled (custom templates are supported in recent versions —
Settings → Subscription → Informationmust show a Sub Theme Directory field) - Root on the VPS
sqlite3— optional, only for the automatic panel setting. Without it the installer copies the file and tells you the one field to set
Still seeing the old page. Append ?html=1 to the subscription URL, and hard-refresh (Ctrl+Shift+R). Recent 3X-UI returns a plain copy-only page to browsers unless ?html=1 or ?view=html is present.
Page is blank. Check that the file is named exactly index.html (or sub.html) and that Sub Theme Directory points at the folder, not the file. Then x-ui restart.
No Sub Theme Directory field. Your 3X-UI predates custom template support — update the panel.
Animations look frozen. The rotating border is driven by requestAnimationFrame, so it works in old webviews too. If it's still static, something is blocking JS on the page.
bash <(curl -Ls https://raw.githubusercontent.com/ehsanh4/3x-ui-theme/main/install.sh)همین. اسکریپت قالب را در /usr/local/x-ui/sub_theme/ کپی میکند، مسیر Sub Theme Directory پنل را به آن اشاره میدهد و x-ui را ریاستارت میکند. بعد کافی است لینک اشتراک هر کاربری را در مرورگر باز کنید.
bash <(curl -Ls https://raw.githubusercontent.com/ehsanh4/3x-ui-theme/main/install.sh) --uninstall۱. فایل index.html را در یک پوشه روی سرور بگذارید، مثلاً /usr/local/x-ui/sub_theme/
۲. در پنل به تنظیمات → اشتراک → Sub Theme Directory بروید و مسیر کامل همان پوشه را وارد کنید
۳. ذخیره کنید و x-ui restart بزنید
حلقهی مصرف با درصد و پشتیبانی از حجم نامحدود، وضعیت فعال/غیرفعال و آنلاین/آفلاین با بروزرسانی خودکار، روزهای باقیمانده با هشدار رنگی، تاریخ شمسی یا میلادی، آمار کامل ترافیک، دکمهی افزودن یکضربهای به Hiddify و Happ و v2Box و v2rayNG و Streisand (فیلترشده بر اساس دستگاه کاربر)، لینکهای Base64 و JSON و Clash همراه QR، لیست کانفیگها با کپی جداگانه، دوزبانه فارسی و انگلیسی، تم روشن و تیره، و نمایش اطلاعیهی پنل با حاشیهی نورانی متحرک.
QR روی خود صفحه تولید میشود و صفحه به هیچ CDN یا اینترنت خارجی نیاز ندارد.
تمام تنظیمات اصلی در بلوک CONFIG در ابتدای index.html است: نام برند، لینک پشتیبانی پیشفرض، زبان پیشفرض، و لیست اپلیکیشنها. رنگها در :root و :root[data-theme="light"] و همهی متنها در آبجکت I18N قرار دارند.
اگر صفحهی قبلی را میبینید، ?html=1 را به انتهای لینک اضافه کنید و با Ctrl+Shift+R رفرش سخت بزنید. اگر صفحه سفید است، مطمئن شوید نام فایل دقیقاً index.html است و مسیر تنظیمشده به پوشه اشاره میکند نه به فایل، سپس x-ui restart بزنید.
Built on 3X-UI's documented subscription template variables, so it runs on a stock panel — no core patching.
Made with ❤️ by ZEVRIX
MIT