/theme-ui

Build consistent, themeable React apps based on constraint-based design principles

Primary LanguageTypeScriptMIT LicenseMIT

Theme UI logo Theme UI logo

Theme UI

The Design Graph Framework

 

GitHub GitHub Stars npm (latest) npm (develop)
Contributors
Size Tree Shaking MIT license Join our Discord community
This project is using Cypress for end-to-end tests. This project is using Percy.io for visual regression testing.


Theme UI is a library for creating themeable user interfaces based on constraint-based design principles. Build custom component libraries, design systems, web applications, Gatsby themes, and more with a flexible API for best-in-class developer ergonomics.

stable docs: https://theme-ui.com
develop (prerelease) docs: https://dev.theme-ui.com


Built for design systems, white-labels, themes, and other applications where customizing colors, typography, and layout are treated as first-class citizens and based on a standard Theme Specification, Theme UI is intended to work in a variety of applications, libraries, and other UI components. Colors, typography, and layout styles derived from customizable theme-based design scales help you build UI rooted in constraint-based design principles.

  • The next evolution of Styled System
  • From the creators of utility-based, atomic CSS methodologies
  • Theme-based styling with the sx prop
  • Compatible with virtually any UI component library
  • Works with existing Styled System components
  • Quick mobile-first responsive styles
  • Built-in support for dark modes
  • Primitive page layout components
  • Completely customizable with robust theming
  • Built with a standard Theme Specification for interoperability
  • Built with Emotion for scoped styles
  • Plugin for use in Gatsby sites and themes
  • Style MDX content with a simple, expressive API
  • Works with Typography.js themes

Getting Started

npm install theme-ui @emotion/react

If you don't need color modes or components you can install @theme-ui/core.

Any styles in your app can reference values from the global theme object. To provide the theme in context, wrap your application with the ThemeUIProvider component and pass in a custom theme object.

// basic usage
import { ThemeUIProvider } from 'theme-ui'
import theme from './theme'

export default (props) => (
  <ThemeUIProvider theme={theme}>{props.children}</ThemeUIProvider>
)

The theme object follows the System UI Theme Specification, which lets you define custom color palettes, typographic scales, fonts, and more. Read more about theming.

// example theme.js
export default {
  fonts: {
    body: 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", sans-serif',
    heading: '"Avenir Next", sans-serif',
    monospace: 'Menlo, monospace',
  },
  colors: {
    text: '#000',
    background: '#fff',
    primary: '#33e',
  },
}

sx prop

The sx prop works similarly to Emotion's css prop, accepting style objects to add CSS directly to an element in JSX, but includes extra theme-aware functionality. Using the sx prop for styles means that certain properties can reference values defined in your theme object. This is intended to make keeping styles consistent throughout your app the easy thing to do.

The sx prop only works in modules that have defined a custom pragma at the top of the file, which replaces the default React JSX functions. This means you can control which modules in your application opt into this feature without the need for a Babel plugin or additional configuration.

/** @jsxImportSource theme-ui */

export default (props) => (
  <div
    sx={{
      fontWeight: 'bold',
      fontSize: 4, // picks up value from `theme.fontSizes[4]`
      color: 'primary', // picks up value from `theme.colors.primary`
    }}
  >
    Hello
  </div>
)

Read more about how the custom pragma works.

Responsive styles

The sx prop also supports using arrays as values to change properties responsively with a mobile-first approach. This API originated in Styled System and is intended as a terser syntax for applying responsive styles across a singular dimension.

/** @jsxImportSource theme-ui */

export default (props) => (
  <div
    sx={{
      // applies width 100% to all viewport widths,
      // width 50% above the first breakpoint,
      // and 25% above the next breakpoint
      width: ['100%', '50%', '25%'],
    }}
  />
)

Documentation

MIT License

Contributors ✨

Thanks goes to these wonderful people (emoji key):


Brent Jackson

πŸ€” πŸ’» 🎨 πŸ“– πŸ’‘ ⚠️ πŸ‘€

Piotr Monwid-Olechnowicz

πŸ’» πŸ“– ⚠️ πŸ‘€ πŸ’‘

Dany Castillo

πŸ’» πŸ“– πŸ’‘ ⚠️

Jordan Overbye

πŸ’» πŸ’‘ ⚠️

Lachlan Campbell

πŸ’» πŸ’‘ ⚠️ πŸ‘€ πŸ“– πŸ’¬

John Otander

πŸ’» πŸ‘€ πŸ“– ⚠️ πŸ€”

David Burles

πŸ’» πŸ‘€ ⚠️ πŸ“–

Max Stoiber

πŸ’» πŸ‘€ ⚠️ πŸ’‘

Atanas Stoyanov

πŸ’» πŸ’¬ ⚠️ πŸ› πŸ“–

Lennart

πŸ’» πŸ› πŸ“– πŸ’‘

Aleksandra Sikora

πŸ’»

LB

πŸ’» ⚠️

Francis Champagne

πŸ’» πŸ› ⚠️ πŸ“–

Alex Page

πŸ’» πŸ“–

Adam Schay

πŸ’»

Alex

πŸ’» πŸ“–

James Edmonds

πŸ’» πŸ“–

Florent SCHILDKNECHT

πŸ’» πŸ“–

Cole Bemis

πŸ’» ⚠️ πŸ“–

John Letey

πŸ“–

Yuraima Estevez

πŸ’»

Allan Pope

πŸ’» πŸ“–

Emmanuel Pilande

πŸ’»

Justin Hall

πŸ’»

Marek

πŸ’» πŸ›

BjΓΆrn Clees

πŸ“– πŸ’»

Iurii Kucherov

πŸ“–

Joe Strouth

πŸ’» πŸ›

Stewart Everett

πŸ’»

Travis Arnold

πŸ’» πŸ“–

Ivo Reis

πŸ’»

Benedikt RΓΆtsch

πŸ› πŸ“–

Jacob Cofman

πŸ“–

John Letey

πŸ“–

Lawrence Gosset

πŸ“–

Markos Konstantopoulos

πŸ“–

Robin Millette

πŸ’»

Rodney Folz

πŸ’»

Rodrigo Pombo

πŸ’» ⚠️ πŸ“–

Scott Silvi

πŸ“–

Shawn Allen

πŸ“–

Tomas Carnecky

πŸ’» πŸ›

John Polacek

πŸ’» πŸ›

mackie

πŸ’»

Aaron Adams

πŸ’» πŸ› πŸ“–

Amberley

πŸ’»

Andreea Năstase

πŸ“–

Anson Low Z.F

πŸ› πŸ“–

Bernhard Gschwantner

πŸ’»

Bhanu Prakash Korthiwada

πŸ“–

Bruno Lemos

πŸ“–

Bryce Fischer

πŸ’»

Dan Wood

πŸ“–

Debs

πŸ“–

Edward O'Reilly

πŸ’» πŸ›

Eric Schaefer

πŸ’»

Felix Green

πŸ“–

Gerhard Bliedung

πŸ’» πŸ›

Guayo Mena

πŸ’‘

Guilherme Lima

πŸ“–

Herb Caudill

πŸ“–

Jacob Bolda

πŸ’» πŸ›

Jason Lengstorf

πŸ› πŸ“–

Jason Rundell (he/him)

πŸ’‘

Joe Race

πŸ“–

Kanstantsin Klimashevich

πŸ“–

Eka

πŸ“– πŸ›

Keir Williams

πŸ“–

KristΓ³f PoduszlΓ³

πŸ’» πŸ› πŸ€”

Kyle Gill

πŸ“–

Kyle Holmberg

πŸ“–

Jay Laiche

πŸ’»

Marc Wiest

πŸ’»

Matheus Teixeira

πŸ’»

matt-cratebind

πŸ“–

Matt Zabriskie

πŸ’»

Maxime Khoy

πŸ’»

Michael Friedman

πŸ“–

Michael Zetterberg fd. Lopez

πŸ’»

Nathan Knowler

πŸ’»

Neeraj Lagwankar

πŸ“–

Owen Young

πŸ’»

Patrick Arminio

πŸ’» πŸ›

Pedro Duarte

πŸ’»

Ray Clanan

πŸ’»

Rich Werden

πŸ“–

Rob Phoenix

πŸ“– πŸ›

Robert Moggach

πŸ’» πŸ›

Anand Narayan

πŸ’» πŸ›

Sam Poder

πŸ“–

Sam Rose

πŸ“–

Sohrab

πŸ’»

Spencer Rinehart

πŸ’»

Steve

πŸ“–

Steve Barton

πŸ“–

Tim Reynolds

πŸ’» πŸ›

VinΓ­cius Lemes

πŸ“–

Yihwan Kim

πŸ’» πŸ›

Yuriy Burychka

πŸ“–

Zolwiastyl

πŸ’»

Amrish Kushwaha

πŸ’»

Joe Bell

πŸ’» πŸ›

kenny-loveholidays

πŸ’»

β¦‡β¦€βˆ™Λ‡βˆŽΛ‡βˆ™β¦€β¦ˆ

πŸ’» πŸ›

navsgh

πŸ“–

Shane O'Neill

πŸ“–

ζ±ͺ磊

πŸ’» πŸ›

Carolin Maisenbacher

πŸ’» πŸ“– ⚠️

Alex Chan

πŸ“– πŸ’‘ ⚠️ πŸ’»

Kenny

πŸ’»

Jordie Bodlay

πŸ“–

Matt Gleich

πŸ“–

William Pei

πŸ“– πŸ’‘ πŸ’» ⚠️

Greg Poole

πŸ“–

Akash

πŸ“– πŸ’»

Cannon Lock

πŸ“–

kamatte

πŸ“– πŸ’»

Simen A. W. Olsen

πŸ“– πŸ’‘ ⚠️ πŸ’»

Wahid Rahim

πŸ“– πŸ’‘ πŸ’»

Justin Cooper

πŸ“–

CJ

πŸ“– πŸ’»

This project follows the all-contributors specification. Contributions of any kind welcome!