oncss is a CSS-in-JS library that provides developers with a powerful css function to style their web applications. It enables modern styling techniques, including nested selectors, responsive design, and dynamic keyframes, all while offering seamless integration with JavaScript frameworks like React.

Installation

Install the oncss package via npm:

npm install oncss

Import the css function in your project:

import css from 'oncss';

Core Concept: The css Function

The css function is the heart of oncss, designed to dynamically generate and inject CSS into your application. It supports:

• CSS Properties: Use standard CSS properties and values.
• Nested Selectors: Apply styles to child elements or states using &.
• Media Queries: Implement responsive designs with @media rules.
• Keyframes: Create animations with @keyframes.
• Global Styles: Apply styles globally with @global.
• Custom Breakpoints: Define reusable breakpoints for responsiveness.
• Other At-Rules: Utilize additional at-rules like @container, @layer, and @supports.

Basic Example

const buttonStyles = css({
  backgroundColor: 'blue',
  color: 'white',
  padding: '10px 20px',
  borderRadius: '5px',
  '&:hover': {
    backgroundColor: 'darkblue',
  },
  '@media (min-width: 768px)': {
    padding: '15px 30px',
  },
});

console.log(buttonStyles);

Configuration Options

The css function can be customized through an options object:

Available Properties

| Property | Type | Description | | ------------- | ---------- | ------------------------------------------------------------------------------------------------- | | classPrefix | string | Adds a prefix to generated class names. | | breakpoints | object | Custom breakpoints for responsive designs. | | aliases | object | Custom shorthand properties for CSS rules. | | injectStyle | boolean | Controls whether styles are auto-injected. | | skipProps | function | Filters out unwanted properties. Receives prop, value, and dept as arguments. | | getValue | function | Transforms property values dynamically. Receives value, prop, css, and dept as arguments. | | getProps | function | Customizes specific property handling. Receives prop, value, css, and dept as arguments. |

Example with Options

const styles = css({
  fontSize: 16,
  padding: 10,
}, {
  classPrefix: 'myprefix',
  breakpoints: {
    sm: 480,
    md: 768,
    lg: 1024,
  },
});

Using Breakpoints

You can use the defined breakpoints in your styles to create responsive designs:

const responsiveStyles = css({
  fontSize: 14,
  padding: {
    sm: 12,
    lg: 24
  },
  
}, {
  breakpoints: {
    sm: 480,
    md: 768,
    lg: 1024,
  },
});

React Integration

oncss integrates seamlessly with React. Simply pass the generated class name to your component.

React Example

import React from 'react';
import css from 'oncss';

const buttonStyle = css({
  backgroundColor: 'green',
  color: 'white',
  padding: '10px 20px',
  borderRadius: '8px',
  '&:hover': {
    backgroundColor: 'darkgreen',
  },
});

function Button() {
  return <button className={buttonStyle.toString()}>Click Me</button>;
}

export default Button;

Advanced Features

Nested Selectors

Apply styles to child elements or pseudo-classes:

const cardStyles = css({
  padding: '20px',
  border: '1px solid #ccc',
  '& h1': {
    fontSize: '24px',
    margin: 0,
  },
  '&:hover': {
    boxShadow: '0 4px 8px rgba(0, 0, 0, 0.1)',
  },
});

Media Queries

Easily add responsive styles:

const responsiveStyles = css({
  fontSize: '14px',
  '@media (min-width: 768px)': {
    fontSize: '18px',
  },
});

Keyframes

Define and use animations:

const animationStyles = css({
  '@keyframes fadeIn': {
    from: { opacity: 0 },
    to: { opacity: 1 },
  },
  animation: 'fadeIn 2s ease-in-out',
});

Global Styles

Apply global styles effortlessly:

const globalStyles = css({
  '@global': {
    body: {
      margin: 0,
      fontFamily: 'Arial, sans-serif',
    },
    a: {
      color: 'blue',
      textDecoration: 'none',
    },
  },
});

Supported At-Rules

oncss supports various CSS at-rules to enhance your styling capabilities. Here is a list of supported at-rules with descriptions:

| At-Rule | Description | | ------------ | ---------------------------------------------------------------------------- | | @media | Used for applying styles based on media queries for responsive design. | | @keyframes | Defines animations that can be applied to elements. | | @global | Applies styles globally across the entire application. | | @container | Used for container queries to apply styles based on container size. | | @layer | Defines style layers to control the order of style application. | | @supports | Applies styles based on the support of specific CSS features in the browser. |

Server-Side Styling

oncss supports server-side rendering (SSR) by utilizing the CSSFactory to store and manage generated CSS styles. This allows you to extract and inject styles into your server-rendered HTML.

Example with React

Here's an example of how to use oncss for server-side rendering with React:

import React from 'react';
import ReactDOMServer from 'react-dom/server';
import css, { CSSFactory } from 'oncss';

const buttonStyle = css({
  backgroundColor: 'blue',
  color: 'white',
  padding: '10px 20px',
  borderRadius: '5px',
  '&:hover': {
    backgroundColor: 'darkblue',
  },
});

function Button() {
  return <button className={buttonStyle}>Click Me</button>;
}

const App = () => (
  <div>
    <Button />
  </div>
);

// Render the component to a string
const html = ReactDOMServer.renderToString(<App />);

let styles: any = Array.from(CSSFactory.values()).map((style) => {
  return `<style data-oncss="${style.classname}">${style.css}</style>`
});

// Inject the styles into the HTML
const fullHtml = `
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>SSR with oncss</title>
  ${styles}
</head>
<body>
  <div id="root">${html}</div>
</body>
</html>
`;

console.log(fullHtml);

In this example, the CSSFactory is used to collect all generated CSS styles during the server-side rendering process. These styles are then injected into the HTML document, ensuring that the styles are applied correctly when the page is loaded in the browser.

Utility Functions

CSSFactory

CSSFactory is a global cache for storing generated CSS styles. It helps in reusing styles and avoiding redundant style generation.

formatCSSProp

formatCSSProp is a utility function that converts camelCase CSS property names to kebab-case.

import { formatCSSProp } from 'oncss';

const formattedProp = formatCSSProp('backgroundColor');
console.log(formattedProp); // 'background-color'

formatCSSValue

formatCSSValue is a utility function that formats CSS values, adding units like px where necessary.

import { formatCSSValue } from 'oncss';

const formattedValue = formatCSSValue('width', 100);
console.log(formattedValue); // '100px'

TypeScript Integration

oncss provides full TypeScript support, allowing you to define types for your CSS properties and options.

Defining CSS Properties

You can define the types for your CSS properties using the CSSProps type:

import { CSSProps } from 'oncss';

interface MyAliases {
  customColor?: string;
}

const styles: CSSProps<MyAliases, 'sm' | 'md' | 'lg'> = {
  backgroundColor: 'blue',
  customColor: 'red',
  '@media (min-width: 768px)': {
    backgroundColor: 'green',
  },
};

Using Options with Types

You can also define types for the options object:

import { CSSOptionProps } from 'oncss';

const options: CSSOptionProps<MyAliases, 'sm' | 'md' | 'lg'> = {
  classPrefix: 'myprefix',
  breakpoints: {
    sm: 480,
    md: 768,
    lg: 1024,
  },
  aliases: {
    customColor: (value) => ({ color: value }),
  },
};

const styles = css({
  fontSize: 16,
  padding: 10,
}, options);

Conclusion

oncss simplifies styling for modern web applications. Its robust feature set, from responsive design to keyframe animations, makes it an invaluable tool for developers.

Author