Custom Captive Portal: HTML and CSS Guide

Custom Captive Portal: HTML and CSS Guide — A Purple Technical Briefing [INTRODUCTION] Welcome to the Purple Technical Briefing series. Today we are getting into the weeds on something that affects every single guest WiFi deployment — the captive portal. Specifically, we are talking about how to write clean, reliable HTML and CSS for a custom captive portal landing page. If you have ever connected to hotel WiFi and been greeted by a broken splash page — missing images, unstyled text, a login button that does not respond to touch — you have experienced what happens when a developer builds a portal without understanding the constraints of the environment it runs in. Today, we are going to make sure that does not happen to you. This briefing is aimed at frontend developers, creative designers, and web developers who are either building a captive portal from scratch or customising an existing template. We will cover the HTML structure, the CSS rules that matter, the Apple CNA mini-browser constraints that trip up even experienced developers, and how platforms like Purple's portal builder can eliminate most of this complexity entirely. Let us get into it. [TECHNICAL DEEP-DIVE] First, let us establish what a captive portal actually is at the network level. When a device connects to a WiFi network that requires authentication, the network intercepts HTTP traffic and redirects the user to a landing page. This is the captive portal. The user sees a splash page, completes an action — entering an email, accepting terms, logging in via social — and the network then grants full internet access. The critical thing to understand is where this page is rendered. On iOS devices, it opens inside Apple's Captive Network Assistant — the CNA — which is a stripped-down WebKit webview. It is not Safari. It has no persistent cookies. It cannot load external resources. It has limited JavaScript support. And it closes the moment the user switches to another app. On macOS, the CNA renders at a fixed 900 by 572 pixels. On Android, modern devices use Chrome Custom Tabs, which are considerably more capable. Windows 10 opens the user's default browser. Samsung devices use Samsung Internet. This platform fragmentation is the single biggest source of broken captive portals in production. Developers test on their Android phone, everything looks great, and then the hotel's iPhone-toting guests get a white screen with unstyled text. So let us talk about how to code defensively. The golden rule for captive portal HTML and CSS is this: treat the page as if it has no internet connection. Because during the authentication phase, it does not. The network is captive. Any resource your page tries to load from an external URL — a Google Font, a CDN-hosted stylesheet, a JavaScript library, a logo image — will fail silently or cause a loading spinner that never resolves. Starting with the HTML structure. Your document should be a clean HTML5 page. In the head, you need a viewport meta tag with content set to width equals device-width and initial-scale equals one. This is non-negotiable for mobile rendering. Without it, iOS will render the page at 980 pixels wide and scale it down, making everything microscopic. Your CSS must be inline — either in a style block within the head element, or as inline style attributes on individual elements. Do not use an external stylesheet linked via a link tag. That stylesheet lives on your server, which the captive network cannot reach during authentication. The page will render completely unstyled. For fonts, use a system font stack. Something like: font-family — apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica Neue, Arial, sans-serif. This tells the browser to use whatever system font is available. Do not use Google Fonts. The import call will fail, and your fallback font will be Times New Roman, which is not the brand experience your client is paying for. For images — your logo, background graphics, decorative elements — you have two options. Either serve them from the same captive portal server, which means they are on the same local network and accessible before authentication completes. Or, better, encode them as Base64 data URIs directly in your HTML or CSS. This eliminates the external dependency entirely. Now let us talk about the page layout. Since over ninety percent of captive portal logins happen on mobile devices, your design should be mobile-first. That means a single-column layout, a maximum width of around 480 pixels, centred on the page. Use flexbox on the body element — display flex, flex-direction column, align-items centre, justify-content centre, min-height 100 viewport height. This centres your content card vertically and horizontally on any screen size. Your primary call-to-action button needs to be touch-friendly. Apple's Human Interface Guidelines specify a minimum tap target of 44 by 44 pixels. In practice, for a primary CTA, you want something more like 48 pixels tall, full width within the container, with a border-radius of around 8 to 12 pixels. For form fields — email input, name input — set the font-size to at least 16 pixels. This is critical. iOS Safari and the CNA will automatically zoom in on any input field with a font-size below 16 pixels, which breaks your carefully crafted layout. Setting font-size to 16 pixels or above prevents this zoom behaviour. The legal consent section deserves particular attention. Under GDPR, if you are collecting personal data — even just an email address — you need explicit, informed consent. This means a checkbox that is unchecked by default, with a visible label that clearly states what the user is consenting to. Do not pre-tick the checkbox. The consent checkbox itself must be clearly visible without scrolling. Now, a critical implementation detail for iOS CNA specifically. When the user completes authentication, the CNA monitors whether the captive domain has become accessible. The check is triggered by full page navigation, not by JavaScript AJAX calls. This means if you build a single-page app that submits the form via fetch or XMLHttpRequest and updates the DOM without a full page redirect, the CNA will never detect that authentication has completed. You must redirect to a new URL after authentication — a full HTTP redirect, not a JavaScript DOM manipulation. This is one of the most common mistakes in captive portal development. For JavaScript, keep it minimal. The CNA has limited JS support and no access to localStorage or sessionStorage. Cookies are destroyed when the CNA closes. Any state management that relies on these browser APIs will fail. Vanilla JavaScript event listeners are fine. jQuery is a 30-kilobyte external dependency that will fail to load. [IMPLEMENTATION RECOMMENDATIONS AND PITFALLS] Let me give you the practical implementation checklist. First: viewport meta tag, always. Second: all CSS inline, no external stylesheets. Third: all images either served from the captive portal server or Base64-encoded. Fourth: system font stack, no web fonts. Fifth: minimum 16 pixel font size on all input fields. Sixth: touch-friendly tap targets, minimum 44 by 44 pixels. Seventh: single column layout, max-width 480 pixels. Eighth: full page redirect on authentication, not a JavaScript state update. Ninth: GDPR-compliant consent checkbox, unchecked by default. Tenth: test on a real iOS device using an actual captive network, not a browser preview. The pitfalls I see most often in production. Number one: Google Fonts — remove the import, it will fail. Number two: external JavaScript libraries — Bootstrap, jQuery, any CDN-hosted script will fail. Number three: CSS variables declared in an external stylesheet — they must be in your inline style block. Number four: background images referenced by URL — Base64 encode them. Number five: AJAX form submission without a post-authentication redirect — the CNA will not detect authentication completion. Now, the honest conversation about building versus buying. Building a custom captive portal from scratch means you are also responsible for the backend infrastructure — the RADIUS server, the database, the SSL certificate, the DNS configuration, the network integration with your access points, and the ongoing security patching. This is a significant engineering commitment. Purple's portal builder gives you a drag-and-drop interface with a custom HTML and CSS editor for developers who need pixel-perfect control, while handling all of the backend infrastructure — the authentication, the data capture, the analytics, the GDPR compliance tooling, and the network integrations with over 200 access point vendors. You get the creative control without the infrastructure overhead. [RAPID-FIRE Q AND A] Can I use CSS Grid in a captive portal? Yes, but test on iOS CNA specifically. Flexbox has broader support in older WebKit versions. Can I use SVG logos? Yes, inline SVGs are fully supported and preferable to Base64-encoded PNGs for logos because they scale perfectly on retina displays. Does the macOS CNA support the same constraints as iOS CNA? Broadly yes, with one difference: macOS CNA renders at a fixed 900 by 572 pixel window. Can I use a CSS framework like Tailwind? Only if you generate a purged, self-contained CSS file and inline it in your style block. What about HTTPS? Your captive portal must be served over HTTP for the initial redirect to work — HTTPS connections cannot be intercepted by the captive network. [SUMMARY AND NEXT STEPS] To summarise today's briefing. A custom captive portal is a constrained web environment, not a standard browser context. The Apple CNA and Android webviews impose strict limitations on external resources, cookies, JavaScript, and session state. The solution is to build self-contained HTML pages with inline CSS, system fonts, Base64-encoded images, and full-page redirects on authentication. For venue operators and IT teams evaluating their options: if your requirement is a fully branded, bespoke portal with custom HTML and CSS, the choice is between building and maintaining the full stack yourself — which is a substantial engineering commitment — or using a platform like Purple that provides the custom HTML and CSS editing capability on top of a production-grade backend infrastructure. The next steps from here: review Purple's portal editor documentation, audit your existing portal against the mobile-first checklist we covered today, and if you are starting from scratch, use the HTML template structure we outlined as your baseline. Thanks for listening, and we will see you in the next briefing.