DEV Community: Yuki Teraoka

withStencil - Stop Writing Skeleton Components Twice

Yuki Teraoka — Thu, 20 Nov 2025 11:40:05 +0000

The Problem with Skeleton Screens

When using React Suspense or client-side data fetching, we often want to show a skeleton as a loading fallback. However, we frequently end up giving up on proper skeleton implementations because:

Writing skeleton JSX is time-consuming and duplicates component structure
Hard to keep skeleton JSX in sync with component changes
Components throw TypeErrors when props are missing
Maintenance burden grows with each component

The Solution: withStencil

withStencil is a HOC that wraps any React component and automatically generates a skeleton version. No need to write duplicate JSX or add conditional branches.

Installation

npm install react-stencilize

Basic Usage

Note: For styling skeletons with Tailwind CSS v4, check out Design Skeletons by Character Count

Design Skeletons by Character Count — Tailwind CSS v4

Yuki Teraoka
Yuki Teraoka

Yuki Teraoka

Follow

Nov 9 '25

Design Skeletons by Character Count — Tailwind CSS v4

#tailwindcss #css #frontend

5 reactions
Comments 1 comment

3 min read

Let's create a UserView component to render user information:

type User = { name: string; bio?: string }

const UserView = (props: { user: User }) => {
  return (
    <div>
      <h4>{props.user.name}</h4>
      <p>{props.user.bio}</p>
    </div>
  )
}

Without props, this component would throw a TypeError. But with withStencil:

import { withStencil } from 'react-stencilize'
import { UserView } from './components/user'

const StencilUserView = withStencil(UserView)

function App() {
  return (
    <>
      {/* Normal rendering with props */}
      <UserView user={{ name: 'John Doe', bio: 'Software Engineer at Example Corp' }} />

      {/* Skeleton rendering without props */}
      <StencilUserView />
    </>
  )
}

StencilUserView preserves the UI structure while replacing only the text and dynamic content with empty values - perfect for skeleton display.

How It Works

withStencil uses three key mechanisms:

1. Deep Safe Proxy

Wraps props with a Proxy that returns safe dummy values at any depth
Prevents crashes on any property access, even deeply nested ones
No TypeErrors when props are missing

2. Recursive Element Transformation

Traverses component output recursively
Converts to skeleton-friendly format while preserving structure

3. Smart Transformation Rules

Strings/numbers → empty strings
Arrays → recursively processed per element
React elements → structure preserved, children recursively transformed
Objects → safely wrapped with Proxy

Using with React Suspense

withStencil shines when used as a Suspense fallback:

import { use, Suspense } from 'react'
import { withStencil } from 'react-stencilize'

type User = { name: string; bio?: string }

const UserView = (props: { user: User }) => {
  return (
    <div>
      <h4>{props.user.name}</h4>
      <p>{props.user.bio}</p>
    </div>
  )
}

const UserCard = (props: { user: Promise<User> }) => {
  const user = use(props.user)
  return <UserView user={user} />
}

// Generate skeleton version
const StencilUserView = withStencil(UserView)

function App() {
  const userPromise = fetchUser() // Promise<User>

  return (
    <Suspense fallback={<StencilUserView />}>
      <UserCard user={userPromise} />
    </Suspense>
  )
}

Key Benefits

Since StencilUserView is derived from UserView:

No layout mismatch between skeleton and actual content
Automatic synchronization - component changes reflect in skeleton
Smooth transitions from loading to loaded states
Zero duplication - single source of truth

Complex Component Example

withStencil works with complex nested components too:

type Post = {
  title: string
  content: string
  author: { name: string; avatar: string }
  tags: string[]
}

const PostView = (props: { post: Post }) => {
  return (
    <article>
      <h1>{props.post.title}</h1>
      <div>
        <img src={props.post.author.avatar} alt={props.post.author.name} />
        <span>{props.post.author.name}</span>
      </div>
      <p>{props.post.content}</p>
      <ul>
        {props.post.tags.map(tag => <li key={tag}>{tag}</li>)}
      </ul>
    </article>
  )
}

const StencilPostView = withStencil(PostView)

// Use as Suspense fallback
<Suspense fallback={<StencilPostView />}>
  <PostView post={post} />
</Suspense>

Even with deeply nested properties, arrays, and complex structures, withStencil safely renders the skeleton version without any TypeErrors.

Why withStencil?

Traditional Approach Problems

// ❌ Duplicate JSX maintenance burden
const UserView = ({ user, skeleton }) => {
  if (skeleton) {
    return (
      <div>
        <h4 className="skeleton"></h4>
        <p className="skeleton"></p>
      </div>
    )
  }
  return (
    <div>
      <h4>{user.name}</h4>
      <p>{user.bio}</p>
    </div>
  )
}

withStencil Approach

// ✅ Single source of truth, automatic skeleton
const UserView = ({ user }) => {
  return (
    <div>
      <h4>{user.name}</h4>
      <p>{user.bio}</p>
    </div>
  )
}

const StencilUserView = withStencil(UserView)

Summary

withStencil HOC automatically generates skeleton versions of React components
No duplicate JSX - changes to components automatically reflect in skeletons
Deep safe Proxy prevents TypeErrors when props are missing
Perfect for Suspense fallback - zero layout mismatch
Works with complex components - nested objects, arrays, any structure

Stop writing skeleton components twice. Share the same component for both normal rendering and skeleton display with withStencil.

Try it in your projects: react-stencilize

Maximize Element Size While Maintaining Aspect Ratio with CSS

Yuki Teraoka — Tue, 11 Nov 2025 11:36:30 +0000

Introduction

When building video players, image viewers, or modal windows, you often need to maintain a specific aspect ratio while maximizing the available space.

This article demonstrates how to combine CSS aspect-ratio and object-fit properties to create a layout that automatically scales to fit its container while preserving a fixed aspect ratio.

Live Demo

See it in action here:
No Dependencies - Maximize While Maintaining Aspect Ratio

Common Challenges

Traditional approaches to maintaining aspect ratios have several drawbacks:

Padding-top hack: Using padding-top: 56.25% (for 16:9) is cryptic and hard to maintain
JavaScript calculations: Requires recalculation on window resize, impacting performance
Limited to images: Works for img tags but difficult to apply to arbitrary elements

The Solution

By combining CSS aspect-ratio and object-fit: contain, you can achieve this with clean, declarative code.

HTML Structure

Use three nested containers:

<div class="container">
  <div class="inner">
    <div class="aspect-ratio-lock">
      <!-- Your contents -->
    </div>
  </div>
</div>

CSS Implementation

.container {
  position: relative;
  width: 100%;
  height: 100%;
}

.inner {
  position: absolute;
  inset: 0;
  max-width: 100%;
  max-height: 100%;
  aspect-ratio: 16 / 9;
  object-fit: contain;
}

.aspect-ratio-lock {
  width: 100%;
  height: 100%;
  /* Your content styles here */
}

How It Works

1. `aspect-ratio: 16 / 9`

Locks the element to a 16:9 ratio. You can use any ratio you need (e.g., 4 / 3, 1 / 1).

2. `position: absolute` + `inset: 0`

Positions .inner absolutely within .container, stretching it to fill the parent.

3. `object-fit: contain`

This is the key property. While typically used with img or video elements, when combined with aspect-ratio, it automatically scales any element to fit within its parent while maintaining the specified ratio.

4. `max-width` / `max-height`

Constrains the element to never exceed the parent's bounds.

Responsive Behavior

The beauty of this approach is that it automatically adapts to the parent's size without any JavaScript:

Tall container → Scales to width (leaves space top/bottom)
Wide container → Scales to height (leaves space left/right)

Everything is handled purely with CSS.

Practical Examples

Video Player Layout

.inner {
  aspect-ratio: 16 / 9; /* Common video ratio */
}

Square Card

.inner {
  aspect-ratio: 1 / 1;
}

Mobile Screen Preview

.inner {
  aspect-ratio: 9 / 16; /* Portrait orientation */
}

Browser Support

aspect-ratio: Chrome 88+, Firefox 89+, Safari 15+
object-fit: Chrome 32+, Firefox 36+, Safari 10+

All modern browsers support this approach. For older browsers, you can provide a fallback using the padding-top hack.

Summary

Combining CSS aspect-ratio and object-fit: contain gives you:

✅ Simple, readable code
✅ No JavaScript required
✅ Support for any aspect ratio
✅ Automatic responsive behavior
✅ Works with any element (not just images)

Design Skeletons by Character Count — Tailwind CSS v4

Yuki Teraoka — Sun, 09 Nov 2025 10:28:59 +0000

Still stacking gray boxes with h-* and w-* for skeletons? That approach has problems:

Layout shifts when switching from skeleton to actual text
Duplicate markup for skeleton-specific elements that don't match your real content structure

This package lets you specify skeletons by character count instead. It only renders when the element is empty, so your normal markup stays intact—no layout shifts, no extra skeleton-only markup.

Try the demo →

Repo: https://github.com/t4y3/tailwindcss-skeleton-screen

Concept

Keep markup as close to normal as possible.

Render skeletons only when the element is :empty.
Use ss-text-[n] to generate a text skeleton for n characters.
Height follows font-size/line-height, so it aligns with typography.

{/* Skeleton is shown only while empty */}
<p className="text-base text-gray-600 ss-text-[71]">{text}</p>

The difference from typical width/height rectangles is visually clear:

Installation (Tailwind CSS v4)

npm install -D tailwindcss-skeleton-screen

Load it in your Tailwind v4 entry CSS (no tailwind.config.js needed):

/* tailwind.css (your entry processed by Tailwind v4) */
@import "tailwindcss-skeleton-screen";

Basic Usage

Just specify the character count; height follows your typography.

<!-- Text skeleton appears only while the element is empty -->
<p class="text-base text-gray-600 ss-text-[71]"></p>

For multiple lines, specify per-line counts with slashes:

<p class="ss-text-[24/24/12]"></p>

Single-line truncation works too:

<p class="truncate ss-text-[40]"></p>

Utilities

ss-object: Block skeleton with background color
ss-text-[n]: Text skeleton for n characters
ss-text-[a/b]: Per-line counts by slash (multiline)

Notes:

Skeletons render only when the element is :empty.
Combine freely with text utilities; it follows your typography.

Customize (v4 `@theme`)

Colors and radii are exposed as CSS custom properties. Override via Tailwind v4 @theme.

@theme {
  --skeleton-color: #e5e7eb; /* default */
  --skeleton-radius: .375rem; /* default (~6px) */
}

Global overrides:

@theme {
  --skeleton-color: #f3f4f6;
  --skeleton-radius: .5rem;
}

Scoped overrides (apply to descendants):

.card {
  --skeleton-color: #e2e8f0;
  --skeleton-radius: .25rem;
}

React Example (render only when empty)

export function UserBio({ bio }) {
  return (
    <p className="text-sm leading-6 text-gray-600 ss-text-[72]">
      {bio}
    </p>
  );
}

The skeleton shows while bio is empty and naturally switches to text once populated.

How It Works

The plugin parses ss-text-[...] and builds a string of full‑width spaces (U+3000).
It injects that as --tw-content into ::before only when the element is :empty.
Background and radius are controlled by CSS variables. It matches your line-height and wrapping.

[class*="ss-text-"]:empty::before {
  content: var(--tw-content);
  background-color: var(--skeleton-color);
  white-space: break-spaces;
  word-break: break-all;
  border-radius: var(--skeleton-radius);
}

Migration from v3

No more plugin registration in tailwind.config.js.
Use v4 CSS directives (@import / @plugin).
Theme options moved to @theme CSS custom properties.

Best Practices

For variable-length content, estimate slightly larger character counts to reduce visual shift.
For layouts with variable line counts, use ss-text-[a/b/c] for the maximum expected lines.
Combine with truncate to match “1 line + ellipsis” from the loading state.

Wrap-up

Designing skeletons by “character count” aligns them with your typography and makes loading states feel natural. Setup is just @import and a utility class. Try it on your existing components.

npm: tailwindcss-skeleton-screen
GitHub: https://github.com/t4y3/tailwindcss-skeleton-screen

DEV Community: Yuki Teraoka

withStencil - Stop Writing Skeleton Components Twice

The Problem with Skeleton Screens

The Solution: withStencil

Installation

Basic Usage

Design Skeletons by Character Count — Tailwind CSS v4

How It Works

1. Deep Safe Proxy

2. Recursive Element Transformation

3. Smart Transformation Rules

Using with React Suspense

Key Benefits

Complex Component Example

Why withStencil?

Traditional Approach Problems

withStencil Approach

Summary

Maximize Element Size While Maintaining Aspect Ratio with CSS

Introduction

Live Demo

Common Challenges

The Solution

HTML Structure

CSS Implementation

How It Works

1. aspect-ratio: 16 / 9

2. position: absolute + inset: 0

3. object-fit: contain

4. max-width / max-height

Responsive Behavior

Practical Examples

Video Player Layout

Square Card

Mobile Screen Preview

Browser Support

Summary

Design Skeletons by Character Count — Tailwind CSS v4

Concept

Installation (Tailwind CSS v4)

Basic Usage

Utilities

Customize (v4 @theme)

React Example (render only when empty)

How It Works

Migration from v3

Best Practices

Wrap-up

1. `aspect-ratio: 16 / 9`

2. `position: absolute` + `inset: 0`

3. `object-fit: contain`

4. `max-width` / `max-height`

Customize (v4 `@theme`)