@stagyra/flex-layout

SCSS flexbox utilities using responsive data attributes. It is useful for demos, internal apps, and Angular projects that want the ergonomics of Angular Flex-Layout without runtime directives.

The package is framework-agnostic CSS. Angular is used only for this repository's demo and packaging workflow.

Install

npm install @stagyra/flex-layout

Import

Use the compiled CSS:

@import "@stagyra/flex-layout/styles/flex-layout.css";

Or import and configure the SCSS source:

@import "@stagyra/flex-layout/styles/flex-layout";

@use "@stagyra/flex-layout/styles/flex-layout" with (
  $fl-pixel-sizes: 0, 8, 16, 24, 32, 64, 128, 256, 512,
  $fl-responsive-pixel-sizes: 0, 8, 16, 24, 32, 64, 128, 256, 512,
  $fl-gap-sizes: 1, 2, 4, 8, 12, 16, 20
);

Layout

<div data-layout="row wrap center p-stretch" data-gap="16px">
  <div data-flex="w50%" data-flex-xs="w100%">Left</div>
  <div data-flex="w50%" data-flex-xs="w100%">Right</div>
</div>

Attribute API

| Attribute | Example | Description | | --- | --- | --- | | data-layout | row wrap center p-center | Enables flex layout, direction, wrap, main-axis, and cross-axis alignment. | | data-layout-{breakpoint} | data-layout-xs="column" | Overrides layout on a responsive breakpoint. | | data-layout-align | space-between p-stretch | Applies alignment without changing direction. | | data-flex | w50%, w320px, auto, basis | Controls an item basis, width, height, growth, shrink, or self alignment. | | data-flex-{breakpoint} | data-flex-lt-md="w100%" | Overrides flex item behavior by breakpoint. | | data-gap | 16px, custom | Applies native flex gap. Use custom with --fl-gap. | | data-offset | w25%, w24px | Applies margin-left. | | data-fill | empty attribute | Sets width and height to 100%. | | data-hide | empty, true, false | Hides when present unless value is explicitly false. | | data-hide-{breakpoint} | data-hide-lt-md | Hides only inside a breakpoint. |

Directions

• row
• row-reverse
• column
• column-reverse

Main-Axis Alignment

• start
• center
• end
• space-between
• space-around
• space-evenly

Cross-Axis Alignment

Prefix cross-axis values with p-:

• p-start
• p-center
• p-end
• p-stretch
• p-baseline
• p-space-between
• p-space-around
• p-space-evenly

Wrap

• wrap
• nowrap
• wrap-reverse

Breakpoints

| Suffix | Media query | | --- | --- | | xs | max-width: 599.98px | | sm | 600px - 959.98px | | md | 960px - 1279.98px | | lg | 1280px - 1919.98px | | xl | min-width: 1920px | | gt-xs | min-width: 600px | | gt-sm | min-width: 960px | | gt-md | min-width: 1280px | | gt-lg | min-width: 1920px | | lt-sm | max-width: 599.98px | | lt-md | max-width: 959.98px | | lt-lg | max-width: 1279.98px | | lt-xl | max-width: 1919.98px |

Size Scale

Percentage utilities include common layout sizes from w5% to w100%, including thirds (w33%, w34%, w66%, w67%).

Pixel utilities for data-flex and data-offset include even pixel values from 0px through 1024px, then every 10px from 1030px through 1920px. The responsive suffixes use the same pixel scale, so values such as data-flex-gt-md="w1440px" are generated.

Gap utilities support only 1px through 20px, plus custom.

Summary of generated size values:

| Utility | Generated values | | --- | --- | | Percent data-flex and data-offset | 5%, 10%, 15%, 20%, 25%, 30%, 33%, 34%, 40%, 45%, 50%, 55%, 60%, 65%, 66%, 67%, 70%, 75%, 80%, 85%, 90%, 95%, 100% | | Pixel data-flex and data-offset | Even values from 0px through 1024px, then every 10px from 1030px through 1920px | | Gap data-gap | Every pixel from 1px through 20px, plus custom |

For values outside the generated scale, or values that should not be generated globally, use CSS custom properties:

<div data-layout="row" data-gap="custom" style="--fl-gap: 18px">
  <aside data-flex="basis" style="--fl-basis: 340px">Filters</aside>
  <main data-flex>Results</main>
</div>

--fl-basis accepts any valid CSS size value, including 520px, 32rem, 45%, calc(100% - 280px), and clamp(280px, 32vw, 520px).

Use breakpoint-specific variables when basis is active in a responsive data-flex-* attribute:

<aside
  data-flex="basis"
  data-flex-xs="basis"
  style="--fl-basis: 320px; --fl-basis-xs: 100%"
>
  Filters
</aside>

Supported variable suffixes match the breakpoint names: --fl-basis-xs, --fl-basis-sm, --fl-basis-md, --fl-basis-lg, --fl-basis-xl, --fl-basis-gt-xs, --fl-basis-gt-sm, --fl-basis-gt-md, --fl-basis-gt-lg, --fl-basis-lt-sm, --fl-basis-lt-md, --fl-basis-lt-lg, and --fl-basis-lt-xl.

Each breakpoint variable falls back to --fl-basis, then to auto.

Reducing CSS in Consumer Apps

Do not run PurgeCSS while building this package, because the package cannot know which utilities a consuming application will use. Run PurgeCSS in the final application build instead, scanning that application's templates and TypeScript files.

Example PurgeCSS configuration:

import { PurgeCSS } from 'purgecss';

const results = await new PurgeCSS().purge({
  content: [
    './src/**/*.{html,ts}',
    './projects/**/*.{html,ts}',
  ],
  css: [
    './node_modules/@stagyra/flex-layout/styles/flex-layout.css',
  ],
  defaultExtractor: (content) =>
    content.match(/[A-Za-z0-9_:%./#()[\]-]+/g) || [],
});

If your app builds attribute values dynamically, safelist the generated patterns that cannot be found as literal strings:

safelist: {
  greedy: [
    /data-layout/,
    /data-flex/,
    /data-gap/,
    /data-offset/,
    /data-hide/,
  ],
}

For best results, prefer literal template values such as data-flex-gt-md="w1440px" when possible. Literal values let PurgeCSS keep only the utilities actually used by the application.

Publish

Build first:

npm run build:lib

Publish manually from the generated package:

cd dist/flex-layout
npm publish --access public