https://github.com/anydigital/breakout-css
Modern CSS utilities to easily break-out / hang / pop-out images, iframes, and other "figures" from their parent container.
https://github.com/anydigital/breakout-css
Last synced: 6 months ago
JSON representation
Modern CSS utilities to easily break-out / hang / pop-out images, iframes, and other "figures" from their parent container.
- Host: GitHub
- URL: https://github.com/anydigital/breakout-css
- Owner: anydigital
- License: mit
- Created: 2025-12-27T01:02:51.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-01-25T06:49:50.000Z (6 months ago)
- Last Synced: 2026-01-25T08:39:24.692Z (6 months ago)
- Language: CSS
- Homepage:
- Size: 158 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# breakout-css
Modern CSS utilities to easily break-out / hang / pop-out / bleed images, tables, iframes, and other figures from their parent container.
## Installation
### From CDN
```html
```
### From Source
```css
@import "@anydigital/breakout-css";
```
^ This is supported by Tailwind v4!
## Usage
### Basic Usage
```html
Article Title
Lorem ipsum dolor sit amet...
More content here...
```
### Supported Elements
The breakout effect automatically applies to direct children or elements wrapped in `
` tags:
**Inline blocks:**
- `img`, `picture`, `figure`, `canvas`, `audio`
**Larger blocks:**
- `table` (responsive with horizontal scroll support), `pre`
- `iframe`, `object`, `embed`, `video`
**Custom utility classes:**
- Elements with `.breakout-item` or `.breakout-item-max` class
### Headings & Dividers
For decorative headings and full-width dividers, use the `.breakout-headings` class. This adds a subtle accent line to the left of headings and makes horizontal rules span the full viewport width:
```html
Section Title
Some content...
Subheading
More content...
```
The extension applies to the following elements (when they don't have other classes):
- `h2`, `h3`, `h4` (adds decorative accent line)
- `hr` (breaks out to full viewport width)
_Note: The decorative accent on headings is automatically hidden if the heading immediately follows an `
` to avoid visual overlap._
### Manual Breakout
For elements that don't automatically break out, use the `.breakout-item` class:
```html
Regular content...
More content...
```
### Force Maximum Width
By default, breakout elements use `width: fit-content` with `max-width: 125%`, allowing them to size between 100% and 125% width based on their content. To force an element to always use the full 125% breakout width, use `.breakout-item-max`:
```html
Regular content...
More content...
```
Note: `.breakout-item-max` uses `width: 125% !important` to override default sizing.
## How It Works
The `.breakout` container acts as a content wrapper that:
1. Sets a smart `max-width: calc(10% + 65ch + 10%)` to ensure an optimal reading line length (approx. 65 characters).
2. Applies `padding-inline: 10%` to create the necessary gutter space for breakout elements to extend into.
The breakout effect on elements is achieved by:
1. Setting `width: fit-content` with `min-width: 100%` and `max-width: 125%` (inline blocks like `img`, `picture`, `figure`, `canvas`, and `audio` use `min-width: auto` instead). Tables are handled specially to be full-bleed (`max-width: 100vw`) with internal horizontal padding (`7.5%`) and horizontal scroll support.
2. Using `margin-left: 50%` to position from the center of the container
3. Using `transform: translateX(-50%)` to shift it left by half its width
This combination allows elements to extend beyond their parent container (up to 125% width) while remaining visually centered.
The `.breakout-headings` utility works by:
1. Adding a `::before` pseudo-element to headings (`h2-h4`) positioned to the left.
2. Using a `100vw` width and negative translation on `hr::before` to create a full-width divider.
### Markdown Support
The breakout effect works on direct children of `.breakout`, or elements wrapped in `
` tags (for Markdown compatibility where images are often wrapped in paragraphs).
## License
MIT