---
title: Tailwind CSS Plugin for Ionic Framework
description: Learn how to create a custom Tailwind CSS plugin for the Ionic Framework to apply platform-specific styles for Android and iOS in your applications.
date: 
  created: 2025-07-07
  updated: 2026-07-17
authors:
  - robingenz
categories:
  - Guides
  - Ionic Framework
faq: true
---

# Tailwind CSS Plugin for Ionic Framework

Tailwind CSS is a popular utility-first CSS framework that allows developers to build custom designs quickly. In this guide, we will show you how to create a simple Tailwind CSS plugin for the Ionic Framework that adds platform-specific variants for Android and iOS.

<!-- more -->

<div class="capawesome-z29o10a">
  <a href="/" target="_blank">
    <img alt="Build and deploy your Capacitor app with Capawesome Cloud" src="https://capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.png?t=1" />
  </a>
</div>

## Introduction

A common requirement for Ionic apps is to apply different styles based on the platform. For example, you might want to use a different background color for Android and iOS. This can be achieved by creating a custom Tailwind CSS plugin that adds platform-specific variants.

## Creating the Plugin

Plugins in Tailwind CSS allow you to extend the framework's functionality by adding custom utilities, components, or variants. In this case, we will create a plugin that adds `ios:` and `android:` variants to target specific platforms.
To create the plugin, you need to set up your Tailwind CSS configuration file (`tailwind.config.js`) and define the custom variants. Here’s how you can do it:

```js
const plugin = require('tailwindcss/plugin');

module.exports = {
  content: ['./src/**/*.{html,ts}'],
  plugins: [
    plugin(function ({ addVariant }) {
      addVariant('android', '.md &');
      addVariant('ios', '.ios &');
    })
  ]
};
```

In this code snippet, we are using the `addVariant` function from Tailwind CSS to create two new variants: `android` and `ios`. The `.md &` selector targets Android devices, while the `.ios &` selector targets iOS devices. This allows us to apply styles conditionally based on the platform. Both, the `md` and `ios` classes are automatically added by Ionic Framework when the app is running on the respective platform.

### Where Do the `ios` and `md` Classes Come From?

Ionic determines the active **mode** — `ios` or `md` — at startup and adds the corresponding class to the root of your app. By default this is based on the platform the app is actually running on (iOS gets `ios`, Android and the web get `md`), but the mode isn't strictly tied to the physical device: it can also be forced explicitly via Ionic's `mode` config, which is useful when you want to preview or test one platform's styling while running on another. Since these Tailwind variants are just CSS selectors keyed off that class, they follow whatever mode Ionic has set — not the raw platform your JavaScript would report from `Capacitor.getPlatform()`.

That distinction matters in practice: if you force `mode: 'ios'` for a demo build running on Android, the `ios:` variant applies and the `android:` variant doesn't, even though the app is technically on an Android device.

???+ info "Tailwind CSS v4 and later"

    If you are using Tailwind CSS v4 or later, you have to declare those variants directly in your CSS file since no Tailwind CSS configuration file is used anymore. You can do this by adding the following code to your CSS file:

    ```css
    @custom-variant android (.md &);
    @custom-variant ios (.ios &);
    ```

## Usage

Now that we have created the plugin, we can use the `ios:` and `android:` variants in our Tailwind CSS classes. For example:

```html
<div class="ios:bg-primary android:bg-secondary">
  This div will have a primary background color on iOS and a secondary background color on Android.
</div>
```

## Real-World Use Cases

Background color swaps are the simplest example, but the more common reason to reach for platform variants is matching each platform's own design conventions — the same way Ionic's built-in components already look different in `ios` vs `md` mode. A few patterns that come up often:

**Button shape.** iOS's Human Interface Guidelines favor fully rounded, pill-shaped buttons, while Material Design uses a smaller, consistent corner radius:

```html
<button class="ios:rounded-full android:rounded-md px-4 py-2">
  Continue
</button>
```

**Tap feedback.** iOS conventionally dims a pressed element's opacity, while Material Design uses a ripple or a visible highlight color. If you're building custom pressable elements instead of relying on `ion-button`, you can express that directly:

```html
<div class="ios:active:opacity-60 android:active:bg-black/10">
  Tap me
</div>
```

**Typography.** Font choice is one of the most common platform differences — iOS defaults to San Francisco, Android to Roboto. If you've registered custom font utilities for each (e.g. `font-sf` and `font-roboto` mapped to platform-appropriate font stacks in your Tailwind theme), the variants let you switch between them declaratively instead of branching in JavaScript:

```html
<p class="ios:font-sf android:font-roboto">
  Platform-native body text
</p>
```

**Spacing and density.** Material Design's spacing scale tends to run slightly denser than iOS's, so list items, form fields, or card padding are a common candidate for a per-platform tweak:

```html
<div class="ios:py-4 android:py-3">
  List item content
</div>
```

None of this replaces safe-area handling for notches, status bars, or home indicators — that's a separate, cross-platform CSS concern covered in [Capacitor Edge-to-Edge & Safe Areas: The Complete Guide](./capacitor-edge-to-edge-and-safe-areas-guide.md). The `ios:`/`android:` variants are about deliberate design differences, not device geometry.

## Bonus: Adding a Web-Specific Variant

If your app also runs as a web build (not just packaged for iOS and Android), you may want to style that case separately from Android, since Ionic applies the same `md` class to both by default. The `ios:`/`android:` variants alone can't distinguish "actually on Android" from "running in a browser," but `Capacitor.isNativePlatform()` can — it returns `false` on the web and `true` on a native iOS or Android build. Add your own class explicitly at startup based on that check:

```typescript
import { Capacitor } from '@capacitor/core';

if (!Capacitor.isNativePlatform()) {
  document.documentElement.classList.add('web');
}
```

Then register a matching variant alongside the other two:

```js
plugin(function ({ addVariant }) {
  addVariant('android', '.md &');
  addVariant('ios', '.ios &');
  addVariant('web', '.web &');
})
```

Or in Tailwind CSS v4:

```css
@custom-variant web (.web &);
```

Now `web:` styles apply only when the app isn't running as a native iOS or Android build — handy for hiding native-only UI (like a status bar spacer) or showing web-only elements (like a "Download the app" banner) without extra JavaScript conditionals scattered through your components.

## FAQ

### How does Ionic decide whether to apply the `md` or `ios` class in the first place?

Ionic detects the running platform at startup (based on `Capacitor.getPlatform()` and the device's user agent) and adds the corresponding mode class — `md` for Android and other Material Design contexts, `ios` for iOS — to the root element automatically. This plugin's variants simply hook into classes Ionic already applies; you don't need to set them yourself.

### Do I need this plugin if my app is web-only and never runs on a real device?

Not usefully — on the web, Ionic still assigns a mode (typically `md` unless you're testing in an iOS-simulating browser context), so the variants technically still work, but the platform-specific styling this plugin is designed for is mainly meaningful once the app actually runs on Android or iOS.

### Why does the Tailwind v4 syntax look so different from the v3 config-based version?

Because Tailwind CSS v4 removed the JavaScript configuration file entirely in favor of CSS-native configuration. `addVariant` inside `plugin(function ({ addVariant }) {...})` was how you registered a custom variant in v3's `tailwind.config.js`; the `@custom-variant` at-rule is v4's direct CSS equivalent, achieving the same result without a config file at all.

### Can I combine the `ios:` and `android:` variants with other Tailwind variants like `hover:` or `dark:`?

Yes — custom variants created with `addVariant` (or `@custom-variant` in v4) compose the same way built-in Tailwind variants do, so combinations like `ios:dark:bg-primary` work as expected, applying only when both conditions are true simultaneously.

## Related Posts

- [Capacitor Edge-to-Edge & Safe Areas: The Complete Guide](./capacitor-edge-to-edge-and-safe-areas-guide.md)
- [Install Tailwind CSS with Ionic Framework](./install-tailwind-css-with-ionic-framework.md)

## Conclusion

With this simple Tailwind CSS plugin, you can easily apply platform-specific styles in your Ionic applications. This approach allows you to maintain a clean and organized codebase while leveraging the power of Tailwind CSS.

To stay updated with the latest updates, features, and news about the Capawesome, Capacitor, and Ionic ecosystem, subscribe to the [Capawesome newsletter](/newsletter/){:target="_blank"} and follow us on [X (formerly Twitter)](https://x.com/capawesomeio){:target="_blank"}.

If you have any questions or need assistance with Capacitor, Ionic Framework, or Tailwind CSS, feel free to reach out to the Capawesome team. We are here to help you build amazing applications with the best tools available.