1. Home
  2. Blog
  3. Progressive Web App (PWA)

Style Only the Installed WordPress PWA With Custom CSS and JS

The first time you open your own site from the home screen icon, something usually looks slightly off. The header sits under the clock. The site name appears twice, once in the app title bar and once in your logo row. A “Get our app” link points visitors to an app they are already using. None of this is wrong on the website, so you do not want to change the website to fix it. WordPress PWA custom CSS is the clean answer: styling that only applies when someone is running your site as an installed app.

Progressify has two fields for exactly this job, PWA Custom CSS and PWA Custom JS. This guide explains what they do, which other settings decide what you need to fix, a set of practical recipes, and how to test changes without fooling yourself with a cached copy.

Why the installed app needs its own styling

An installed PWA is the same WordPress site, but it runs in a different frame. Progressify’s Web App Manifest tab sets the Display Mode, and the default is standalone. In standalone mode the app opens in its own window with no browser chrome. That one change has knock-on effects:

  • There is no address bar or browser back button. Your own navigation has to do that work.
  • The operating system draws its own title area. On many devices this shows your app name and is tinted with your Theme Color, which can make a logo bar directly below it feel redundant.
  • The page can run closer to the edges of the screen. On iOS, if you choose the black-translucent iOS Status Bar Style, the content extends underneath the status bar. Progressify’s documentation is direct about it: that style needs your layout to account for the area behind the bar, or your header will sit under the clock.
  • Website-only elements stop making sense. Install prompts that your theme or another plugin prints, “download our app” banners, and some sticky bars written for desktop browsing.

Fixing these in the theme means writing app-only conditions and remembering them at every theme update. Progressify keeps that code in one place and loads it only in the installed app.

What Progressify gives you

Both fields live under Progressify > Settings > UI Components, in the Custom CSS and JS section.

  • PWA Custom CSS (Pro). CSS applied only when the site is running as an installed PWA. The documentation suggests it for adjustments that should not affect ordinary web visitors, such as padding for a device notch or hiding a header that duplicates the app title bar.
  • PWA Custom JS (Pro). JavaScript loaded under the same condition.

In the settings array these are stored as pwaCustomCss and pwaCustomJs, both empty by default. That matters if you manage settings in code or through the REST API, because you can version the snippet with the rest of your site configuration.

There is one important warning in the docs. These fields run on your front end with no validation. A syntax error in the JS field can break scripts on the page. Test on staging first.

Free and Pro, so you know what you are working with

The free Progressify on WordPress.org is a complete, working PWA. Pro adds the app-like layer. For this guide the split looks like this:

SettingFreePro
Display mode, start page, orientationYesYes
Theme color and background colorYesYes
iOS status bar styleNoYes
Navigation tab barNoYes
PWA Custom CSS and PWA Custom JSNoYes
Platform support (General tab)YesYes

Locked settings stay visible in the admin with a Pro badge, so you can see the fields before deciding. Pro is part of the DaftPlug membership, one license for every DaftPlug Pro plugin, with plans that differ only by number of sites. See pricing.

Settle these settings before you write any CSS

Custom CSS is the last step, not the first. A few settings change what the installed app looks like, and each one changes what you need to correct.

Display mode

Check Progressify > Settings > Web App Manifest > Display Mode. The options are:

ValueWhat visitors get
standaloneIts own window with no browser chrome. The usual choice.
fullscreenCovers the whole screen, including the system status bar. Suited to games and media.
minimal-uiIts own window with a minimal set of browser controls such as back and reload.

If you pick fullscreen, you will almost certainly need top padding. If you pick minimal-ui, there is a back control, so you may not need to add navigation. The docs recommend pairing standalone with the navigation tab bar or swipe navigation, because standalone relies on your own in-app navigation.

iOS status bar style

The iOS Status Bar Style setting (Pro, iOS only) has three values: default (white bar, black text), light-content (black bar, white text), and black-translucent (transparent bar, white text, content extends underneath). If your brand looks best with your header color running all the way to the top of the screen, black-translucent gets you there, and PWA Custom CSS is where you add the padding to keep the header clear of the clock.

Theme and background color

Theme Color tints the title bar of the installed app and the browser toolbar on mobile. Background Color is shown on the splash screen while the app boots, before your CSS loads. Getting these right removes a surprising amount of the “something looks off” feeling before you touch CSS. The related guide on splash screen, theme colour, and display mode walks through those settings in detail.

Platform support

Progressify > Settings > General decides where features are active: any mix of mobile browsers, desktop browsers, and installed PWAs. Selecting Installed PWAs alone keeps the public site untouched and loads components like the navigation tab bar only after install. Know your choice, because the tab bar changes how much bottom space you need.

Recipes for common fixes

Every theme is different, so treat the selectors below as placeholders. Open developer tools, find the real class or ID on your site, and replace them. Keep each block commented so the next person knows why it is there.

1. Hide a header row that repeats the app title

If the operating system already shows your app name, a full logo bar underneath it eats vertical space on a small screen.

/* Installed app only: the title bar already shows the app name */
.site-branding .site-title,
.site-description {
  display: none;
}

Hide the duplicate text, not the whole header, if the header also holds your menu or search.

2. Keep the header clear of the notch and status bar

On devices with a notch or a translucent status bar, the browser exposes the unsafe areas as CSS environment variables.

/* Installed app only: push the header below the status bar */
.site-header {
  padding-top: env(safe-area-inset-top);
}

One caveat from how browsers work rather than from Progressify: env(safe-area-inset-*) values are only non-zero when the page’s viewport meta tag includes viewport-fit=cover. Check your theme’s <head> output. If that is missing, the variables resolve to zero and you will need a fixed value instead, tested on the devices your visitors actually use.

3. Leave room for the navigation tab bar

The Navigation Tab Bar (Pro) is a fixed bar of tabs pinned to the bottom of the screen on mobile. A fixed bar can cover the last lines of your footer or a sticky “add to cart” button.

/* Installed app only: space for the bottom tab bar */
body {
  padding-bottom: calc(64px + env(safe-area-inset-bottom));
}

Measure the real height of the tab bar in developer tools and adjust the number. Also check your theme’s own floating elements, such as a back-to-top button or chat bubble, which may need moving up by the same amount.

4. Remove website-only calls to action

If your theme has a “Download our app” link, a newsletter bar written for first-time visitors, or a button that opens your own install page, those are noise inside the app.

/* Installed app only: visitors already installed the app */
.header-app-promo,
.footer-install-link {
  display: none;
}

This recipe is for promos that come from your theme or page builder, not for Progressify’s own prompts.

When to reach for PWA Custom JS

Most installed-app fixes are CSS. JavaScript is useful when you need a hook for something CSS cannot select, or when you want the rest of your stack to know the visitor is in the app.

A small, safe example is adding a class to the root element, so other styles or analytics scripts can check it:

// Installed app only: flag the document for other scripts and styles
document.documentElement.classList.add('is-installed-app');

With that class in place, a stylesheet loaded by your theme can use .is-installed-app selectors, and a tag manager can read it to label sessions. Keep the field short. It loads on every page of the installed app, it has no validation, and an error here can stop other scripts on the page.

Leave out large libraries, anything that writes data, and code that duplicates a Progressify feature. Pull down refresh, shake refresh, toast messages, dark mode, and smooth page transitions already exist as settings.

Test it properly

  1. Work on staging first. The docs recommend it for both fields, and a staging site with a real HTTPS certificate behaves like production. Browsers exempt localhost from the HTTPS requirement, so a local test can pass when the live site would not.
  2. Install the app on a real phone. Desktop emulation is useful for layout, but status bars, notches, and gestures behave differently on hardware.
  3. Confirm the manifest. In developer tools, open Application > Manifest to see the display mode and colors the browser actually read. Progressify also serves the manifest at https://example.com/?progressify_manifest=1 if you want to read the JSON directly.
  4. Reload after saving. If a change does not show, a cache is usually serving an old copy. The Progressify troubleshooting guide suggests unregistering the service worker in Application > Service Workers and reloading. If editors keep hitting stale content, consider the Network-First caching strategy and a lower cache expiration time.
  5. Clear caches from the outside in. There may be three layers: the service worker, a page cache plugin, and a CDN.
  6. Check the website too. Open the same page in a normal tab and confirm nothing changed for regular visitors.

If the CSS never appears in the installed app, check platform support first. If installed PWAs are not selected, nothing Progressify adds will load there. Then confirm your Pro license is active, since both fields are Pro.

Keep the snippet maintainable

Comment every block with the reason, prefer hiding and spacing over restyling, and revisit the rules after theme updates, because a renamed class silently turns a rule into a no-op. Since the values live in pwaCustomCss and pwaCustomJs, you can also keep a copy in version control with your other settings.

FAQ

Does PWA Custom CSS affect visitors in a normal browser?

No. Progressify applies it only when the site is running as an installed PWA. Ordinary web visitors get your theme exactly as it is.

Can I use it on the free version?

No. PWA Custom CSS and PWA Custom JS are Pro settings. The fields stay visible with a Pro badge on the free plugin.

Should I use it instead of a dark mode stylesheet?

Use Progressify’s Dark Mode setting if you want a derived dark palette, or your theme’s own dark mode if it has one. The docs warn that running both makes them fight. Custom CSS is for layout corrections, not a second palette.

What if my theme already detects standalone mode?

Then pick one place. Two sets of installed-app rules, one in the theme and one in Progressify, are hard to debug. Keeping them in Progressify means a theme switch does not lose them.

Wrap up

An installed app should feel intentional, not like a website squeezed into a window. Set display mode, colors, status bar style, and platform support first, then use PWA Custom CSS for the handful of spacing and visibility fixes that only make sense inside the app. Keep JavaScript minimal, test on a real phone, and clear caches before deciding something did not work.

Progressify’s Pro settings, including the navigation tab bar, iOS status bar style, and both custom fields, come with the DaftPlug membership. Explore Progressify or compare plans on the pricing page.