CSS light-level Media Feature

What You’ll Learn

The light-level media feature adapts styles to ambient lighting — dim rooms, normal indoor light, or bright glare. Learn the syntax and when it makes sense to use this experimental feature.

Introduction

Some devices have ambient light sensors that measure how bright the surroundings are. The @media (light-level) feature lets CSS respond to that reading — dimming the UI in a dark room or softening glare in direct sunlight.

This is different from the user choosing dark mode. Light-level reacts to the physical environment, which can change as the user moves outdoors, enters a cinema, or turns off room lights.

Definition and Usage

Write @media (light-level: dim), @media (light-level: normal), or @media (light-level: washed) to target each lighting condition. Always provide default styles for devices without light sensors.

📝 Syntax

Use one of three keywords inside an @media rule:

@media (light-level: normal) {
  /* Typical indoor lighting */
}

@media (light-level: dim) {
  /* Low ambient light — dark room */
}

@media (light-level: washed) {
  /* Very bright — glare, direct sunlight */
}

Accepted Values

• normal — Typical lighting; neither unusually dark nor excessively bright (default for most environments).
• dim — Low ambient light; increase contrast and consider darker backgrounds to reduce eye strain.
• washed — Very high ambient light; soften harsh whites and reduce glare for outdoor or sunny conditions.

Three Lighting Conditions

light-level vs prefers-color-scheme

Basic Example

body {
  background-color: #fff;
  color: #1e293b;
}

@media (light-level: dim) {
  body {
    background-color: #1e293b;
    color: #f8fafc;
  }
}

@media (light-level: washed) {
  body {
    background-color: #e2e8f0;
    color: #334155;
  }
}

Default Value

When no sensor is available, browsers typically treat the environment as normal. Your base CSS should work without any light-level rules.

Syntax Rules

• One keyword per query: (light-level: dim).
• Always define readable defaults outside media queries.
• Treat as progressive enhancement — most browsers won’t match today.
• Combine with prefers-color-scheme for broader theme support.
• Do not rely on light-level for critical accessibility alone.

Related Topics

• inverted-colors — system color inversion
• color — display color bit depth
• height — viewport height queries

When to Use light-level

Reach for light-level when ambient lighting affects readability:

• Future-ready designs — Prepare for devices with ambient light sensors.
• Outdoor apps — Soften UI in washed (sunny) conditions.
• Night reading — Darker, higher-contrast UI in dim environments.
• Kiosk / field devices — Hardware that moves between indoor and outdoor light.
• Learning media queries — Understand environment-based responsive design.

Examples Gallery

Practice light-level with background themes, dim-mode contrast, washed-mode glare reduction, and fallback patterns.

@media (light-level: normal) {
  body {
    background-color: #fff;
    color: #1e293b;
  }
}

@media (light-level: dim) {
  body {
    background-color: #1e293b;
    color: #f8fafc;
  }
}

@media (light-level: washed) {
  body {
    background-color: #e2e8f0;
    color: #334155;
  }
}

.article {
  padding: 1.5rem;
  line-height: 1.6;
}

@media (light-level: dim) {
  .article {
    background: #0f172a;
    color: #f1f5f9;
    font-weight: 500;
  }
  .article a {
    color: #93c5fd;
    text-decoration: underline;
  }
}

.card {
  padding: 1rem;
  background: #fff;
  box-shadow: 0 4px 16px rgba(0,0,0,0.1);
  border-radius: 0.5rem;
}

@media (light-level: washed) {
  .card {
    background: #e2e8f0;
    box-shadow: none;
    border: 1px solid #94a3b8;
  }
}

/* Broad fallback — user dark mode preference */
@media (prefers-color-scheme: dark) {
  body {
    background: #1e293b;
    color: #f1f5f9;
  }
}

/* Experimental — physical dim environment */
@media (light-level: dim) {
  body {
    background: #0f172a;
  }
}

@media (light-level: washed) {
  body {
    background: #cbd5e1;
    color: #1e293b;
  }
}

💬 Usage Tips

• Defaults first — Base styles must work without any light-level match.
• Layer with color-scheme — Use both for preference and environment.
• Dim = darker UI — Reduce screen brightness perception with dark backgrounds.
• Washed = softer UI — Avoid pure #fff and heavy shadows outdoors.
• Monitor spec changes — Experimental features evolve; recheck MDN periodically.

⚠️ Common Pitfalls

• Assuming browser support — Very few browsers implement light-level today.
• Confusing with dark mode — User preference ≠ ambient sensor reading.
• Requiring sensors — Never make core UX depend on light-level.
• Over-darkening in dim — Still maintain WCAG contrast ratios.
• Ignoring fallbacks — Always ship readable default styles.

♿ Accessibility

• WCAG contrast — Meet 4.5:1 text contrast in all light levels.
• User control — Don’t override explicit theme preferences without reason.
• Photosensitivity — Avoid flashing between themes on sensor changes.
• Baseline readability — Good defaults help users without sensors.
• Test manually — Simulate dim/washed styles in DevTools for review.

💡 Best Practices