npm package: @gladeye/tailwind-fluid-plugin
Description: A Tailwind CSS plugin for fluid scaling based on screen or container sizes.
Author: @gladeye
Latest version: 1.3.7

# Tailwind CSS Fluid Scaling Plugin

A Tailwind CSS plugin that enables fluid scaling using CSS clamp(). This plugin creates smooth transitions between different viewport sizes for properties like spacing, typography, and dimensions.

## Demo

https://gladeye-tailwind-fluid-plugin.vercel.app/

## Viewport-Based Fluid Scaling

Use the `-fluid-[]` modifier with supported properties to create smooth scaling between breakpoints:

```html
<div class="pt-fluid-[sm=1,md=2,lg=4,xl=8]">
  <!-- Padding-top scales smoothly between breakpoints -->
</div>
```

## Container Query-Based Fluid Scaling

The plugin also supports container queries using the `@` prefix to specify container sizes:

```html
<!-- Define a container (named or not) -->
<div class="@container/main">
  <!-- Element that scales based on container size -->
  <div class="h-fluid-[@container/main,@3xs=100px,@3xl=400px]">
    <!-- Height scales smoothly between container sizes -->
  </div>
</div>
```

## Usage

The plugin provides fluid scaling utilities in the format: `{property}-fluid-[breakpoints]`

### Syntax

#### Viewport Syntax

```
{property}-fluid-[breakpoint1=value1,breakpoint2=value2,...]
{property}-fluid-[value1,value2]
```

#### Container Syntax

```
{property}-fluid-[@containerName,breakpoint1=value1,breakpoint2=value2,...]
{property}-fluid-[@containerName,value1,value2]
```

Where:

- `property` is the CSS property to scale (see supported properties below)
- `containerName` is the name of the container to scale the property for. This is required for container query scaling.
- `breakpoints` are your defined screen/container sizes (sm, md, lg, etc.) if the breakpoint is omitted, the plugin will use the min/max breakpoints defined in the @theme section
- `values` can be Tailwind theme spacing values, explicit dimensions(px or rem)

# Examples:

```
/* Using Tailwind spacing units */
<div className="mb-fluid-[4,6]"/>
```

```
/* Using pixel units */
<div className="mb-fluid-[10px,23px]"/>
```

```
/* Using rem units */
<div className="mb-fluid-[3rem,6rem]"/>
```

```

/*Using container query*/

<div className="@container">
  <div className="h-fluid-[@container,100px,300px]"/>
</div>
```

```
/* Using named container query */
<div className="@container/foo">
  <div className="h-fluid-[@container/foo,100px,300px]"/>
</div>
```

## Demo

https://gladeye-tailwind-fluid-plugin.vercel.app/

## Setup

In your globals.css add the following

```css
@import "tailwindcss";
@plugin "@gladeye/tailwind-fluid-plugin";

@theme {
  /* the Figma design for the smallest screen size */
  --breakpoint-design-min: 320px;
  /* the Figma design for the largest screen size */
  --breakpoint-design-max: 1320px;
  /* the Figma design for the smallest container size */
  --breakpoint-c-min: 2rem;
  /* the Figma design for the largest container size */
  --breakpoint-c-max: 10rem;
  /* the smallest breakpoint to which the fluid scaling scales to */
  --breakpoint-clamp-min: 320px;
  /* the largest breakpoint to which the fluid scaling scales to */
  --breakpoint-clamp-max: 1680px;
}
```

### Custom Fluid Scaling Variables

You can define custom fluid scaling variables in your `@theme` section that will be automatically calculated and available throughout your application. This is useful for values that need to scale fluidly but are used in multiple places.

```css
@theme {
  /* Define the breakpoints for your fluid variable, if omitted it will default to  --breakpoint-design-min/max values */
  --fluid-site-gutter-breakpoint-design-min: 320px;
  --fluid-site-gutter-breakpoint-design-max: 1320px;
  /* Define the fluid scaling clamp breakpoints for your fluid variable, if omitted it will default to --breakpoint-clamp-min/max values */
  --fluid-site-gutter-breakpoint-clamp-min: 320px;
  --fluid-site-gutter-breakpoint-clamp-max: 1680px;
  /* Define the values for your fluid variable */
  --fluid-site-gutter-value-min: 16px;
  --fluid-site-gutter-value-max: 24px;

  /* Adding them to the "spacing" namespace makes "sgs" available for utility classes, e.g "ml-sgs */
  --spacing-sgs: var(--fluid-site-gutter);
}
```

The plugin will automatically:

1. Calculate the fluid scaling between the min and max values
2. Create a CSS variable named `--fluid-{name}` that you can reference
3. Apply the fluid scaling based on the defined breakpoints

The naming convention for the theme variables is:

- `--fluid-{name}-breakpoint-design-min`: The minimum breakpoint, if omitted it will default to `--breakpoint-design-min` value
- `--fluid-{name}-breakpoint-design-max`: The maximum breakpoint, if omitted it will default to `--breakpoint-design-max` value
- `--fluid-{name}-breakpoint-clamp-min`: The smallest breakpoint to which the fluid scaling scales to
- `--fluid-{name}-breakpoint-clamp-max`: The largest breakpoint to which the fluid scaling scales to
- `--fluid-{name}-value-min`: The minimum value
- `--fluid-{name}-value-max`: The maximum value

The resulting fluid variable will be available as `--fluid-{name}`.

### Supported Properties

#### Container and Screen Sizes

- [container sizes](https://tailwindcss.com/docs/responsive-design#container-size-reference)
- [screen sizes](https://tailwindcss.com/docs/responsive-design#fluid-sizing)

#### Tailwind Properties

- `inset`
- `top`
- `right`
- `bottom`
- `leading`
- `left`
- `w`
- `h`
- `max-w`
- `max-h`
- `min-w`
- `min-h`
- `text`
- `tracking`
- `space-x`
- `space-y`
- `p`
- `pt`
- `pr`
- `pb`
- `pl`
- `px`
- `py`
- `m`
- `mt`
- `mr`
- `mb`
- `ml`
- `mx`
- `my`
- `gap`
- `gap-x`
- `gap-y`
- `size`

## How It Works

The plugin calculates fluid values using CSS `clamp()` to create smooth transitions between breakpoints. For example, if you use:

```html
<div class="mt-fluid-[sm=1,lg=4]"></div>
```

The plugin will:

1. Convert the values to pixels
2. Calculate the appropriate scaling ratio
3. Generate a CSS clamp function that smoothly transitions between the values
4. Apply the fluid scaling at the specified breakpoints

## Browser Support

This plugin uses CSS `clamp()` which is supported in all modern browsers. For browser compatibility details, check [Can I Use](https://caniuse.com/?search=clamp).