# GuardianSuit **Repository Path**: binghe021/GuardianSuit ## Basic Information - **Project Name**: GuardianSuit - **Description**: No description available - **Primary Language**: JavaScript - **License**: GPL-3.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-21 - **Last Updated**: 2026-08-21 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Captive Portal Template

If you like my work and appreciate my commitment, you can buy me a coffee.

Buy Me A Coffee

If you want to customize this template to your own needs, please contact me! ( mix@proask.pl ) I offer professional help in customizing solutions that perfectly match your requirements. Write what you need, and together we will create something exceptional! 🚀

## What is a Captive Portal? A Captive Portal allows you to force authentication or redirect to a clickable page to access the network. This is commonly used in hotspot networks, but is also widely used in corporate networks or small local area networks (e.g. shopping malls, restaurants, hotels, airports, etc.) as an additional layer of security for wireless or internet access. OPNsense’s unique template manager makes setting up your own login page an easy task. At the same time it offers additional functionalities, such as: - URL redirection - Option for your own Pop-up - Custom Splash page To read more about the captive portal, I suggest you have a look here: [OPNsense Captive Portal](https://docs.opnsense.org/manual/captiveportal.html?highlight=captive%20portal) ## 🛡️ GuardianSuit – Project Name (since v2.6.0) Starting from version 2.6.0, the Captive Portal Template is identified under the name GuardianSuit. The name is used for project identification, documentation, and further development. Earlier versions remain fully compatible, and the change does not affect configuration or usage. The repository itself will not be replaced or migrated — only its name will change at a later stage. All history, issues, releases, and existing links will remain preserved by GitHub. ## Demo OPNsense Captive Portal Page - [Globe animation](https://opnsense.myhome.cool:8001) - [Globe animation WCAG](https://opnsense.myhome.cool:8002) - [Birds animation](https://opnsense.myhome.cool:8003) - [Cells animation](https://opnsense.myhome.cool:8004) - [Fog animation](https://opnsense.myhome.cool:8005) - [Halo animation](https://opnsense.myhome.cool:8006) - [Net animation](https://opnsense.myhome.cool:8007) - [Rings animation](https://opnsense.myhome.cool:8008) - [Waves animation](https://opnsense.myhome.cool:8009)

login: demo
password: demo

## ⚖️ License and Commercial Version - Current and future versions of the template (v2.2.0 and above) are free for non-commercial use only. - A commercial version will be released soon, including additional features and available for use in commercial projects. - Features available in the free version remain compliant with the non-commercial use policy, and any premium features present in the commercial version will not be included in the GPL/free version. ## 🌐 Multilingual Support The captive portal templates that I have seen so far most often lack multilingual support. I've always wondered why it should only be in English or only in one language at all? Well, let's look below. This template supports multilingualism, checks your preferred browser language, saves a cookie with information about which language was read or which language you chose using the selector. Uses language translations saved in the **xx.json** file. So, according to the layout, you can prepare your own translation, which you later have to declare in the **settings.json** file in the **config** directory. The first (and probably most important) "default_lang" key specifies what language will be loaded by default when the Captive Portal client's web browser's preferred language is different from the languages ​​supported by the platform. ``` "default_lang": "en" ``` In the current release, the settings key defines the default language that will be loaded in case the client browser language is not available in our available languages ​​configuration: ``` "langs": { "en": "English", "pl": "Polski", "sk": "Slovenčina", "fr": "Français", "de": "Deutsch", "nl": "Nederlands", "no": "Norsk", "sv": "Svenska", "fi": "Suomi", "es": "Español", "ca": "Català", "ja": "日本語", "ko": "한국어", "zh": "中文", "pt": "Português", "it": "Italiano", "da": "Dansk", "cs": "Čeština", "lb": "Lëtzebuergesch", "lt": "Lietuvių", "lv": "Latviešu", "et": "Eesti", "el": "Ελληνικά", "bg": "Български", "ro": "Română", "hr": "Hrvatski", "ga": "Gaeilge", "mt": "Malti", "sl": "Slovenščina", "hu": "Magyar", "is": "Íslenska", "sr": "Srpski", "bs": "Bosanski", "me": "Crnogorski", "mk": "Македонски", "sq": "Shqip", "ka": "ქართული", "kk": "Қазақша", "kn": "ಕನ್ನಡ", "hy": "Հայերեն", "tr": "Türkçe", "uk": "Українська", "af": "Afrikaans", "am": "አማርኛ", "ar": "العربية", "ay": "Aymar aru", "az": "Azərbaycanca", "bn": "বাংলা", "cy": "Cymraeg", "eu": "Euskara", "fa": "فارسی", "tl": "Filipino", "gl": "Galego", "gn": "Avañe'ẽ", "gu": "ગુજરાતી", "he": "עברית", "hi": "हिन्दी", "id": "Bahasa Indonesia", "mi": "Māori", "mn": "Монгол", "ml": "മലയാളം", "mr": "मराठी", "ms": "Bahasa Melayu", "nb": "Norsk bokmål", "nn": "Norsk nynorsk", "ne": "नेपाली", "si": "සිංහල", "dz": "རྫོང་ཁ", "sw": "Kiswahili", "th": "ไทย", "uz": "Oʻzbek", "ur": "اُردُو", "vi": "Tiếng Việt", "zu": "IsiZulu", "ky": "Кыргызча", "dv": "ދިވެހި", "ha": "Hausa", "ku": "کوردی (سۆرانی)", "kmr": "Kurdî (Kurmancî)", "pa": "ਪੰਜਾਬੀ", "ps": "پښتو", "sy": "ܣܘܪܝܝܐ", "yi": "ייִדיש", "rw": "Kinyarwanda", "so": "Soomaali", "tg": "Тоҷикӣ", "mg": "Malagasy", "my": "မြန်မာဘာသာ", "km": "ភាសាខ្មែរ", "la": "Latina", "sm": "Gagana Samoa", "sn": "chiShona", "lo": "ພາສາລາວ", "ta": "தமிழ்", "ti": "ትግርኛ", "te": "తెలుగు", "to": "Lea faka-Tonga", "qu": "Runa Simi", "rn": "Ikirundi", "xh": "IsiXhosa", "st": "Sesotho", "tn": "Setswana", "ss": "SiSwati", "nd": "isiNdebele", "aa": "Afar", "be": "Беларуская" } ``` The langs_iso parameter, which was previously included in the configuration, has been removed from the manual settings. In the new template version, ISO values ​​for languages ​​are automatically generated based on the keys defined in the "langs" section. Based on the keys of the langs variable object, the template will automatically determine whether it should display the LTR or RTL content. If only one translation language is defined in the "langs" group, then the language switcher will not be included in the layout. The language translation will be based on the language defined in the "default_lang" key. The base64 logo is set in the **settings.json** file. Due to the universal application, the frame of the image of the logo must keep the proportions of a square. ## Login Control Configuration Group `"login"` A mechanism that allows a specified number of failed login attempts. After exceeding the allowed number of attempts, the ability to log in will be blocked for a specified period of time. Of course, this is not a perfect protection against an attempt to force credentials, but the Captive Portal in OPNsense does not yet have a similar protection. ``` "login": { "control": false, "attempts": 3, "delay": 10 }, ``` - `control` - false: disabled, true: enabled - `attempts` - Allowed number of login attempts - `delay` - Time in minutes that must elapse before the next login ## Layout Configuration Group `"layout"` #### 📋 Offcanvas Menu (since v2.6.0) Version 2.6.0 introduces a fully configurable Offcanvas Menu, allowing administrators to extend the Captive Portal with additional navigation elements such as documentation, offers, privacy information, or custom links. #### 🔧 Layout Configuration The menu can be enabled and positioned directly from the layout configuration group in settings.json: ``` "layout": { "enable_rules": true|false, "enable_menu": true|false, "menu_position": "left|right", "redirect_url": "" }, ``` - `enable_rules` – Enables or disables the required consent to the provisions contained in the ISP provider's Regulations. - `enable_menu` – Enables or disables the Offcanvas Menu - `menu_position` – Defines the menu position (left or right) - `redirect_url` – Redirection url address. If the value is not set or the set value is not a valid url address, the redirection functionality to the specified address will not be implemented. Menu position automatically adapts to LTR / RTL layouts On small screens, the menu width adjusts automatically for optimal usability #### 🌐 Menu Definition in Language Files All menu elements are defined inside language JSON files (e.g. en.json, pl.json). This allows full multilingual support and easy customization without touching JavaScript code. #### 📦 Menu Structure ``` "menu": { "title": "GuardianSuit Menu", ... } ``` #### Menu Elements (itemX) Each menu item is defined as an object with the following properties: ``` "item1": { "title": "Internet", "icon": "I", "href": "https://yourdomain.com/#", "target": "_blank" } ``` - `title` – Text displayed in the menu - `icon` – - single character → rendered as a colored icon badge - HTML entity → rendered as-is (e.g. §) - `href` – - `string` → standard link - `object` → modal definition - `target` – `_blank` or `_self` (in the modal definition the target parameter is not taken into account) #### Modal-Based Menu Items Menu items can open modal windows instead of links: ``` "item6": { "title": "Privacy Policy", "icon": "§", "href": { "type": "modal", "title": "privacy_title", "subtitle": "privacy_subtitle", "content": "privacy_content", "iconText": "§" }, "target": "_self" } ``` Modal content keys (title, subtitle, content) are resolved from the same language file, ensuring full translation support. #### 🧩 Menu Groups Menu items are organized using groups, which control visual grouping and order: ``` "group1": { "title": "Offer", "items": ["item1", "item2", "item3"] } ``` Groups define logical sections inside the menu The items array references previously defined menu items Order in the array determines display order #### 🎨 Icon Rendering Rules Single-character icons automatically receive: - unique background colors (non-repeating per render) - automatic text color contrast (dark/light) HTML entity icons are rendered without background styling This ensures visual consistency and accessibility without manual styling #### The appearance of the language selector can be changed by setting values in the layout section. ``` "layout": { "lang_layout": "select", "lang_flags_dir": "4x3", }, ``` #### Available modes `lang_layout`: - `flags-select` – a drop-down selector with language names and flags - `flags-only-select` – a drop-down selector with flags only (no text) - `flags-list` – a list of flags displayed side by side (no text) - `select` – a classic drop-down selector with language names (no flags) #### Flag directory `lang_flags_dir`: - `4x3` – a 4:3 flag aspect ratio (standard rectangular) - `1x1` – a square flag aspect ratio #### Automatic locale and flag mapping `force_locales_data`: ``` "layout": { "force_locales_data": true|false, } ``` - When `true`, updates `langsFlags` and `langISOMap` from the browser's `navigator.language`. - Only modifies entries if a region is present (e.g., `en-CA`, `pt-BR`). - Leaves two-letter languages (e.g., `en`, `fr`, `es`, `pt`) unchanged. #### Accessibility options: ``` "layout": { "a11y": true|false, "a11y_contrast": true|false, "a11y_keyboard": true|false, "a11y_highlight": true|false, "a11y_mono": true|false, "a11y_helper": true|false, "a11y_helper_breakpoint": 1200, "a11y_factor": 0.5, "a11y_threshold": 0.5, }, ``` - `a11y` – global accessibility toggle - when false, other options are ignored - `a11y_contrast` – automatically adjusts the color contrast of modals and UI elements to make them easier to read, this is based on the `a11y_factor` and `a11y_treshhold` parameters - `a11y_keyboard` – enables keyboard shortcut support: - ⇧ Shift (left) + ⌥ Alt (left) + U - focus on the Username field - ⇧ Shift (left) + ⌥ Alt (left) + P - focus on the Password field - ⇧ Shift (left) + ⌥ Alt (left) + A - check/uncheck the "I accept the terms and conditions" checkbox - ⇧ Shift (left) + ⌥ Alt (left) + R - opens a modal window with the terms and conditions - ⇧ Shift (left) + ⌥ Alt (left) + I - click the active login button - ⇧ Shift (left) + ⌥ Alt (left) + O - log out - ⇧ Shift (left) + ⌥ Alt (left) + L - click the language switcher trigger - ⇧ Shift (left) + ⌥ Alt (left) + M - click the Offcanvas menu trigger **Language shortcuts (⇧ Shift + two letters)** Hold ⇧ Shift and press two letters of the language code (ISO 639-1) at once or one after the other Examples: - ⇧ Shift + P + L → switches to Polish (pl) - ⇧ Shift + E + N → switches to English (en) - ⇧ Shift + D + E → switches to Deutsch (de) - ⇧ Shift + F + R → switches to Français (fr) - ⇧ Shift + E + S → switches to Español (es) - ⇧ Shift + I + T → switches to Italiano (it) - `a11y_highlight` – highlights the currently focused element (e.g., input, button) to facilitate keyboard navigation - `a11y_mono` – monochrome mode reduces the colors in the interface to visually simplify the UI (optional) - `a11y_helper` – interactive Accessibility Tour Guide: - Provides a step-by-step, WCAG-compliant tour of the portal - Highlights and explains all key elements, including username/password fields, login/logout buttons, the "accept rules" checkbox, and language selector - Fully keyboard-navigable: use arrow keys to move between steps, Enter/Space to confirm, Esc to exit - Dynamically adapts to the selected portal language - Adds visual focus indicators to help users see which element is currently highlighted - `a11y_helper_breakpoint` - specifies the minimum viewport width (in pixels) at which the Accessibility Tour Guide trigger is displayed. On smaller screens (e.g., smartphones), the trigger is automatically hidden to avoid UI clutter - `a11y_factor` – contrast adjustment factor for `a11y_contrast` - higher values = greater contrast increase - `a11y_threshold` – contrast threshold – specifies the minimum contrast required between the background and text colors. If the current contrast is below this value, it is automatically adjusted. ## CSS Configuration Group `"css_params"`

"css_params": {

"bg_section": "#252828" ← 1 → Global background color of the entire login section
"bg_image": "" ← 2 → Optional background image displayed over bg_section
"bg_repeat": "no-repeat" ← 3 → Defines background image repeat behavior
"bg_position": "center center" ← 4 → Position of the global background image
"bg_size": "cover" ← 5 → Scaling method of the global background image
"bg_attachment": "" ← 6 → Controls background image scroll behavior (fixed / scroll)
"bg_color_left_side": "" ← 7 → Background color of the left panel
"bg_img_left_side": "url('/images/bg_left_side.png')" ← 8 → Background image of the left panel
"bg_img_left_side_repeat": "no-repeat" ← 9 → Repeat behavior of the left panel background image
"bg_img_left_side_position": "top left" ← 10 → Position of the left panel background image
"bg_img_left_side_size": "cover" ← 11 → Scaling method of the left panel background image
"bg_img_left_side_attachment": "" ← 12 → Scroll behavior of the left panel background image
"bg_left_side_blend": "linear-gradient(0deg, #005f6b4d 0%, #005f6bbf 83.85%)" ← 13 → Gradient overlay blended with the left panel background image
"logo_bg_color": "rgba(249, 253, 255, 1)" ← 14 → Background color of the logo container
"logo_bg_border_radius": "6px 6px 6px 6px" ← 15 → Border radius of the logo container
"bg_color_right_side": "rgba(249, 253, 255, 1)" ← 16 → Background color of the right panel
"bg_img_right_side": "" ← 17 → Background image of the right panel
"bg_img_right_side_repeat": "no-repeat" ← 18 → Repeat behavior of the right panel background image
"bg_img_right_side_position": "top left" ← 19 → Position of the right panel background image
"bg_img_right_side_size": "cover" ← 20 → Scaling method of the right panel background image
"bg_img_right_side_attachment": "" ← 21 → Scroll behavior of the right panel background image
"bg_right_side_blend": "" ← 22 → Optional gradient overlay for the right panel background
"left_side_shadow": "0 0 40px 0 rgba(0, 0, 0, .35)" ← 23 → Shadow cast by the left panel
"right_side_shadow": "0 0 40px 0 rgba(0, 0, 0, .35)" ← 24 → Shadow cast by the right panel
"bg_alternate": "#818a91" ← 25 → Alternate background color used for UI accents and borders
"color_primary": "#7a7a7a" ← 26 → Main text color
"color_secondary": "#ffffff" ← 27 → Secondary text color
"color_alternate": "#373a3c" ← 28 → Alternate text color (labels, placeholders)
"link_color": "#348893" ← 29 → Default link color
"link_hover_color": "#f12184" ← 30 → Link hover color
"input_field_color": "#e8e8e8" ← 31 → Text color inside input fields
"input_field_label_color": "#373a3c" ← 32 → Label color for input fields
"input_field_bg_color": "#ffffff" ← 33 → Background color of input fields
"input_field_border_color": "rgba(145, 156, 167, .27)" ← 34 → Border color of input fields
"input_field_border_radius": "5px 0px 0px 5px" ← 35 → Border radius of input fields
"input_field_before_bg_color": "#00b5cb" ← 36 → Background color of input prefix element
"input_field_after_bg_color": "#00b5cb" ← 37 → Background color of input suffix element
"input_field_placeholder_color": "#373a3c" ← 38 → Placeholder text color
"button_bg_color": "#00b5cb" ← 39 → Primary button background color
"button_hover_bg_color": "#f12184" ← 40 → Primary button hover background color
"button_color": "#ffffff" ← 41 → Primary button text color
"button_hover_color": "#ffffff" ← 42 → Primary button hover text color
"lang_switcher": "#00b5cb" ← 43 → Language switcher main background
"lang_switcher_trigger": "#009db1" ← 44 → Language switcher trigger background
"lang_switcher_link": "#5aecff" ← 45 → Language option link color
"lang_switcher_hover": "#f12184" ← 46 → Language option hover background
"lang_switcher_dropdown": "#216f7a" ← 47 → Language dropdown background
"lang_switcher_dropdown_hover": "#f12184" ← 48 → Language dropdown hover background
"fadein": "0.5s" ← 49 → Fade-in animation duration after page load
"block_padding": "50px" ← 50 → Inner padding of left and right panels
"left_side_block_radius": "15px 15px 15px 15px" ← 51 → Border radius of left panel content wrapper
"right_side_block_radius": "15px 15px 15px 15px" ← 52 → Border radius of right panel content wrapper
"helper_bg_color": "#00b5cb" ← 53 → Background color of the TourGuide helper button
"helper_color": "#ffffff" ← 54 → Text/icon color of the TourGuide helper button
"helper_size": "78px" ← 55 → Width and height of the TourGuide helper button
"offcanvas_margin": "15px" ← 56 → Margin around the offcanvas menu
"offcanvas_trigger_border_radius": "8px 8px 8px 8px" ← 57 → Border radius of the offcanvas trigger button
"offcanvas_trigger_bg_color": "#00b5cb" ← 58 → Background color of the offcanvas trigger button
"offcanvas_trigger_bg_hover_color": "#f12184" ← 59 → Background color of the offcanvas trigger button on hover
"offcanvas_trigger_color": "#ffffff" ← 60 → Text/icon color of the offcanvas trigger button
"offcanvas_trigger_hover_color": "#ffffff" ← 61 → Text/icon color of the offcanvas trigger button on hover
"offcanvas_bg_color": "#ffffff" ← 62 → Background color of the offcanvas menu panel
"offcanvas_border_radius": "8px 8px 8px 8px" ← 63 → Border radius of the offcanvas menu panel
"offcanvas_text_color": "#373a3c" ← 64 → Main text color inside the offcanvas menu
"offcanvas_link_bg_color": "transparent" ← 65 → Background color of offcanvas menu links
"offcanvas_link_bg_hover_color": "#00b5cb1a" ← 66 → Background color of offcanvas menu links on hover
"offcanvas_link_color": "#348893" ← 67 → Text color of offcanvas menu links
"offcanvas_link_hover_color": "#f12184" ← 68 → Text color of offcanvas menu links on hover

};

## Modal Configuration Group `"modal"`

"modal": {

"auth_failed_header_color": "#f12184" Color of the header for the authentication failed modal
"conn_failed_header_color": "#f12184" Color of the header for the connection failed modal
"show_rules_header_color": "#4ca1af" Color of the header when showing ISP rules or regulations modal
"bg_color": "#ffffff" Background color of the modal content area
"icon_color": "rgba(255, 255, 255, .5)" Default color of icons inside the modal
"overlay_color": "rgba(0,0,0,.3)" Background overlay color covering the page when modal is visible
"timeout": 5000 Time in milliseconds after which the modal automatically closes (0 = no auto-close)
"zindex": 1050 Z-index used for the modal to ensure it appears above other content

};

## Animate Configuration Group `"animate"`

"animate": {

"effect": "globe", Selected animation (available: birds, cells, fog, globe, halo, net, rings, waves)
"params": { Common parameters for all effects
"el": "#animate-js", CSS id where the animation will be embedded
"bg_position": "center center", Set the position of the background
"mouseControls": true, Controlling animation by mouse movement
"touchControls": true, Controlling animation by swiping on the touch screen
"gyroControls": false, Controlling animations with the gyrocompass of mobile devices
"minHeight": 200.00,  
"minWidth": 200.00  
},  
"preset": { Animation presets
... Other configuration keys - here I refer to the Vanta.js online configurator https://www.vantajs.com/
}  

};

## What has changed in the template recently: - Further work on the development of the template is planned, hence the bootstrap 5.3.8 and jquery 3.7.1 libraries have been included, at the same time libraries provided natively by OPNsense will not be used - Some functions have been separated from the API, their notation has been changed - A method for dynamically loading scripts into the template has been added - in the current version it is used by vanta.js dependencies, eventually it will be used more widely - The layout has been changed, which was modeled on the Login Screen Design prepared by **Ankur Tripathi** - CSS declarations have been improved, rtl support has been improved - Particles.js has been abandoned, **Vanta.js** has been implemented in its place - thanks and respect to [@tengbao](https://github.com/tengbao/vanta) - great job! The following effects are available: **birds**, **cells**, **fog**, **globe**, **halo**, **net**, **rings** and **waves**, which can be configured in a simplified way in settings.json in the **animate** key as the preferred **effect**, its **params** and the **preset** of the declared effect. - Slovak translation included - thanks to [@Gouster4](https://github.com/Gouster4). - Optimizing the code of javascript functions. - Splitting CSS into smaller portions, nesting CSS selectors. - Blocking the ability to log into the system for a specified period of time, after a specified number of possible attempts. - Logo update for OPNsense v25 - many thanks for the update and vigilance to [@OctoCharm](https://github.com/OctoCharm). - Language selector layout modified. - Expanded digital accessibility support (**WCAG**). - Introduced a new interactive Accessibility Tour Guide (TourGuide) compliant with WCAG 2.1 AA. - Automatic locale and flag mapping has been added, updating flags and locales based on the browser's language while keeping two-letter language codes unchanged. - Added a new **Offcanvas Menu** with configurable position and items. - New translations generated using AI for multiple languages, including new locales: Shona (`sn`), Tongan (`to`), Telugu (`te`), Tamil (`ta`), Samoan (`sm`), Punjabi (`pa`), Norwegian Nynorsk (`nn`), Marathi (`mr`), Malayalam (`ml`), Kannada (`kn`), Latin (`la`), Maori (`mi`), Kazakh (`kk`), Abkhazian (`ab`), Luxembourgish (`lb`), Aymara (`ay`), Guarani (`gn`), Quechua (`qu`), and Belarusian (`be`).