Install

Container CSS is distributed on npm. Install it locally and import the components you need.

npm install container-css

Usage with npm

Option 1: Direct usage (script tags + link tag)

This package ships prebuilt ESM files that you can load directly in the browser.

Important: browsers cannot access node_modules by default. You must either:

• Serve your project with a dev server that can serve node_modules (for example Vite during development), or
• Copy the files you need from node_modules/container-css/ into your app's public/static folder for production.

<link rel="stylesheet" href="node_modules/container-css/fouc-prevention.css">

<script src="node_modules/container-css/static.js" type="module"></script>
<script src="node_modules/container-css/container-box.js" type="module"></script>
<script src="node_modules/container-css/container-flex.js" type="module"></script>
<script src="node_modules/container-css/container-flexrow.js" type="module"></script>
<script src="node_modules/container-css/container-flexcol.js" type="module"></script>

Option 2: Bundler usage (recommended for frameworks)

Register all components:

import 'container-css';

Or import individual components:

import 'container-css/container-box.js';
import 'container-css/container-flex.js';
import 'container-css/container-flexrow.js';
import 'container-css/container-flexcol.js';

To prevent flash of unstyled content (FOUC), include the stylesheet:

import 'container-css/fouc-prevention.css';

Download (No Build Step)

If you don't want to install from npm, you can download the compiled modules directly from this site.

You can download each file individually and use them as you wish. It's handy to download only what you need.

• ContainerBox: container-box.js
• ContainerFlex: container-flex.js
• ContainerFlexRow: container-flexrow.js
• ContainerFlexCol: container-flexcol.js

These modules share a small runtime chunk that must also be present alongside the files above:

• Shared runtime: static.js

Usage

Import the components you want to use:

// Import the files you wish to use
import 'static.js';
import 'container-box.js';
import 'container-flex.js';
import 'container-flexrow.js';
import 'container-flexcol.js';

Or you can simply add these to the top of your html as script tags:

<script src="static.js" type="module"></script>
<script src="container-box.js" type="module"></script>
<script src="container-flex.js" type="module"></script>
<script src="container-flexrow.js" type="module"></script>
<script src="container-flexcol.js" type="module"></script>

HTML Usage

Once imported, use the components directly in your HTML:

<container-flexcol gap="2">
  <container-box p="2" bg="lightgray">Header</container-box>
  <container-box p="3" bg="white">Content</container-box>
  <container-box p="2" bg="lightgray">Footer</container-box>
</container-flexcol>

Preventing Flash of Unstyled Content (FOUC)

Web components can briefly display unstyled content while JavaScript loads and registers the custom elements. Container CSS provides a stylesheet to prevent this.

Option 1: Import the FOUC Prevention Stylesheet (Recommended)

Import the provided CSS file to automatically hide all Container CSS components until they're defined:

// In your JavaScript entry point
import 'container-css/fouc-prevention.css';

Or in your HTML:

<link rel="stylesheet" href="fouc-prevention.css">

Or in your main CSS file:

@import 'fouc-prevention.css';

This can be downloaded from here: fouc-prevention.css

Option 2: Copy the CSS Directly

If you prefer to manage the CSS yourself or want to customize it, you can copy this snippet:

/* Hide custom elements until they're defined */
container-box:not(:defined),
container-flex:not(:defined),
container-flexrow:not(:defined),
container-flexcol:not(:defined) {
  display: none;
}

This uses the :not(:defined) pseudo-class to hide elements until the browser registers them. Once the components are defined, they'll appear with their proper styling applied.

Optional: Fade-in Effect

For a smoother appearance, you can add a fade-in transition:

container-box:not(:defined),
container-flex:not(:defined),
container-flexrow:not(:defined),
container-flexcol:not(:defined) {
  opacity: 0;
}

container-box:defined,
container-flex:defined,
container-flexrow:defined,
container-flexcol:defined {
  opacity: 1;
  transition: opacity 0.2s ease-in;
}

Styling Slotted Children with CSS Classes

Container CSS components use Shadow DOM, which means external CSS cannot style the component internals. However, you can add classes to the custom elements to style their slotted children (the content you place inside the tags).

How It Works

Classes on the custom element host can be used to target child elements in the light DOM:

<style>
  /* Style children of elements with the 'hero' class */
  .hero h1 {
    color: #667eea;
    font-size: 3rem;
    margin: 0;
  }
  
  .hero p {
    color: #666;
    font-size: 1.2rem;
  }
  
  /* Style children of elements with the 'card' class */
  .card img {
    width: 100%;
    border-radius: 8px;
  }
</style>

<container-box class="hero" p="4" bg="white">
  <h1>Welcome</h1>
  <p>This is styled via the .hero class</p>
</container-box>

<container-flexcol class="card" gap="1" p="2">
  <img src="photo.jpg" alt="Photo">
  <h2>Card Title</h2>
</container-flexcol>

Important Notes

• Classes style children, not the container: The class on the custom element cannot style the container itself (e.g., .hero { background: red } won't work). Use component properties for container styling.
• Use for content styling: This pattern is ideal for styling the content you slot into the containers.
• Combine with properties: Use component properties for layout/container styles, and CSS classes for content styles.

Example: Themed Sections

<style>
  .dark-theme h2 { color: white; }
  .dark-theme p { color: #ccc; }
  
  .light-theme h2 { color: #333; }
  .light-theme p { color: #666; }
</style>

<container-box class="dark-theme" p="3" bg="#1a1a1a">
  <h2>Dark Section</h2>
  <p>Content styled with dark theme</p>
</container-box>

<container-box class="light-theme" p="3" bg="#f5f5f5">
  <h2>Light Section</h2>
  <p>Content styled with light theme</p>
</container-box>

TypeScript

TypeScript definitions are included. The components are fully typed for IDE autocomplete support.