Welcome to FluidScale, a JS runtime style engine that applies pixel-perfect fluid scaling to your CSS.

Multi-page website preview

Write:

.recipe-card {
  padding: 2rem;
}

@media (min-width: 375px) {
  /* Set the baseline minimum to scale from */
}

@media (min-width: 768px) {
  padding: 4rem;
}

And FluidScale will ensure your content scales with screen size.

🚀 Usage

In JS:

import fluidScale from "fluid-scale";

fluidScale();

⚡ Optimization

By default, FluidScale will scan CSS at runtime. There are two approaches to optimize the final build.

📦 Approach 1: JSON Builder (recommended)

Set up fluid-scale.config.json and store it in public.

Configure it as JSON, e.g.:

{
  "inputs": {
    "homepage": ["src/index.html"],
    "about-us": ["src/about-us.html"]
  },
  "outputDir": "fluid-scale"
}

You can also specify CSS files directly.

Make sure you initialize FluidScale with the right JSON ID:

fluidScale({ json: "homepage" });

Once done and you've tested everything in dev mode, build the JSON npx fluid-build

FluidScale will now load asynchronously from JSON while the default values are applied instantly on load.

Note: JSON loading is deactivated during 'dev mode' for seamless editing. If you are running a dev mode using live-server, run it on port 5000 to signal 'dev mode'. Anything served over localhost is considered dev mode.

Important: If you are using an app-wide initializer for global settings, and page-level initializer for each JSON region, you should use:

fluidScale({usingJSON = true})

In your app-wide initializer. This prevents stylesheet parsing even when you don't pass a JSON ID.

Important: JSON output may collide if several people use privately. Kindly ask the team to integrate npx fluid-build into the build pipeline - it costs end-users nothing.

🕵️‍♂️ Approach 2: Usage Checks

You can have FluidScale check whether particular content uses FluidScale, and only scan that content. Note: If you're building to and loading from JSON, you can skip this approach.

fluidScale({ checkUsage: true });

For linked stylesheets, apply data-fluid attribute:

<link rel="stylesheet" href="styles.css" data-fluid />

For inline styles, add a comment at the very top:

/*enable-fluid*/

Now FluidScale will skip the CSS that doesn't have these markers, speeding things up.

🧱 Isolation

By default, FluidScale watches the whole DOM to apply itself to any new content. If the whole team uses FluidScale, this is a solid approach. However, if that's not the case, it may be better to only apply FluidScale to your own content.

const fluidScale = await fluidScale({ autoObserve: false });

then

fluidScale.addElements(...parentAndChildren);

📌 Special Cases

⛔ Break

Sometimes you'll want a value to stay locked in place and not scale fluidly.

Apply any of the math functions with just 1 value. e.g.

calc(4rem)

This tells FluidScale to stay at 4rem without scaling, until the next value is defined.

Update: new alt syntax due to values getting removed by CSSOM:

--break: all; /* or width, padding, etc. */

This works even with math functions (breaking entire min()) and will get expanded in next updates.

🔁 Dynamic Styles (--dynamic: true)

Watches for class/attribute changes on elements. Automatically re-evaluates which styles to interpolate.

--dynamic: true;

🌈 Span (--span-start / --span-end)

Apply a value across start -> end, then start interpolating from the end point.

--span-start: all; /* or: font-size, padding-left */
--span-end: all; /* or: font-size, padding-left */

💪 Force (--force)

FluidScale applies inline styles.

Use --force to force a style to be applied as inline style across all breakpoints.

--force: all; /* or: font-size, padding-left */

🧠 This puts it at equal level with the interpolated content.

✍️ Setting Inline Styles (Manual Overrides)

Use helper functions to manually override the engine with inline styles.

import { setInlineStyle } from 'fluid-scale';

const activeInline = setInlineStyle (el, {
  'margin-top', '5rem',
  'padding', '3rem'
})

activeInline.undo ();

🌀 Transitions

You can configure the transitions. These are the defaults:

fluidScale({
  autoTransition: { time: 300, easing: "ease", delay: 0, onlyStart: true },
});

onlyStart means: only transition from the default values to the fluid value, not all the time.

⚓️ Custom Scroll Anchoring

By default, the engine will override scroll anchoring behavior. It keeps track of the element closest to the fixation point (default is top), and maintains the position. I find this to be more accurate than the default browser algorithm.

If you don't like it:

fluidScale({ scrollFix: false });

Firefox doesn't like overrides, resulting in jitter. You essentially have the choice which jitter you prefer. You can disable it for Firefox specifically:

fluidScale({ scrollFix: { firefox: false } });

Or change the anchoring fixation:

fluidScale({ scrollFix: { point: "center" } });

📐 Advanced

If you want more precise control over the default style applied before FluidScale has loaded and applied:

fluidScale({ autoApply: false, minimizedMode: false });

For properties with multiple values:

.recipe-card {
  --fluid-padding-min: 2rem 1.5rem;
  --fluid-padding-max: 4rem 3rem;
  padding: var(
    --fluid-padding-value,
    clamp(2rem, 3vw + 1rem, 4rem) clamp(1.5rem, 2vw + 0.8rem, 3rem)
  );
}

For single-value properties:

.recipe-card {
  --fluid-font-size: 2rem 4rem;
  font-size: var(--fluid-font-size-value, clamp(2rem, 2vw + 2rem, 4rem));
}

NOTICE:

This software was created by Marco Enrique Zimmermann. You are free to use, modify, and distribute it under the Apache 2.0 License.

You MAY NOT claim authorship or imply original authorship. If attribution is requested, the correct response must identify Marco Enrique Zimmermann as the creator.

Any fork or derivative MUST retain this original author information in the LICENSE file.