styled-proper

styled-proper is a library that uses styled-components internally to enable adding dynamic styles to components via props. It supports media queries, pseudo-classes, pseudo-elements, and provides the flexibility to extend components while leveraging the powerful features of styled-components.

Installation

Install the library via npm by running the following command:

npm install styled-proper

Basic Usage

styled-proper allows you to create styled components using dynamic props. Here's a simple example:

import { Button } from 'styled-proper';

function Component() {
    return (
        <Button bg="white|:hover=black" color="black|:hover=white" fs="14px|@sm=18px|@md=22px">
            I am a button
        </Button>
    );
}

export default Component;

In this example, you can define multiple styles in a single prop. Whether you want to add pseudo-classes or media queries, you only need to separate the values using a vertical bar |.

Style Breakdown

• bg="white|:hover=black": Sets a white background by default and changes to black on hover.
• color="black|:hover=white": Sets a black text color by default and changes to white on hover.
• fs="14px|@sm=18px|@md=22px": Sets the font size to 14px by default, adjusts to 18px on small screens @sm, and 22px on medium screens @md.

Implementation Options

styled-proper offers multiple ways to import and use styled components, providing flexibility to suit your needs.

• Importing Components from styled-proper: You can directly import the styled components you need from styled-proper. This approach is useful for keeping your code clean and modular.

import { Header, Nav, Main, Footer, ..., Button } from 'styled-proper';

function Component() {
    return (
        <Main p="1rem">
            <Header w="100%" p="1rem" flexXY="justify,center" bg="white">
                <Nav w="100%" p="1rem">
                    <Button bg="black" color="white">Click me!</Button>
                </Nav>
            </Header>
        </Main>
    );
}

• Importing Groups of Components: If you prefer to organize components into categories or groups, you can import entire sections such as Box, Text, Media, etc. This approach is helpful for managing large sets of components.

import { Box, Text, Media, FormElement, TableElement, MetaElement, Misc } from 'styled-proper';

function Component() {
    return (
        <Box.Main p="1rem">
            <Box.Header w="100%" p="1rem" flexXY="justify,center" bg="white">
                <Box.Nav w="100%" p="1rem">
                    <FormElement.Button bg="black" color="white">
                        Click me!
                    </FormElement.Button>
                </Box.Nav>
            </Box.Header>
        </Box.Main>
    );
}

• Creating Custom Components with the Proper Function: You can use the Proper function to create custom components and tailor them to your needs. This is especially useful if you need full control over component names and configurations.

import Proper from 'styled-proper';

const Button = Proper('button');
const Header = Proper('header');
const Nav = Proper('nav');
const Main = Proper('main');

function Component() {
    return (
        <Main p="1rem">
            <Header w="100%" p="1rem" flexXY="justify,center" bg="white">
                <Nav w="100%" p="1rem">
                    <Button bg="black" color="white">
                        Click me!
                    </Button>
                </Nav>
            </Header>
        </Main>
    );
}

• Extending Components Created with styled-components:

  You can extend components created with styled-components while still using the dynamic prop system provided by styled-proper.

import styled from 'styled-components';
import Proper from 'styled-proper';

const ButtonWithStyledComponents = styled.button`
    padding: 10px;
`;

const ExtendedButton = Proper(ButtonWithStyledComponents);

<ExtendedButton p="1rem">Click me!</ExtendedButton>;

Media Query Support

styled-proper makes it easy to add responsive styles using media queries. To define them, simply prepend the @ symbol to the alias of the desired media query.

Media Query Example:

Below is an example where the aliases @sm and @md are used to adjust the font size based on the screen width:

<Text.P fs="14px|@sm=18px|@md=22px">Hola</Text.P>

• 14px: Default font size.
• @sm=18px: Changes the font size to 18px when the screen width is greater than or equal to 640px.
• @md=22px: Changes the font size to 22px when the screen width is greater than or equal to 768px.

Supported Media Queries:

Pseudo-Class Support

With styled-proper, you can handle pseudo-classes like hover, focus, nth-child, active, and more. The syntax is intuitive and similar to CSS: prepend a : to the pseudo-class name, followed by the desired value separated by =.

Important Note:

Pseudo-class names must be in camelCase format. Examples include:

• hover
• focus
• active
• nthChild
• lastChild

Example with hover Pseudo-Class:

<Button bg="black" color="white|hover:green">
    click me
</Button>

Description:

• bg="black": Fondo negro por defecto.
• color="white|:hover=green": El color del texto cambia a verde cuando el botón está en estado hover.

Example with active Pseudo-Class:

<Button bg="black" color="white" border="1px solid white|active:green">
    click me
</Button>

Description:

• border="1px solid white": Default border is white.
• border="|:active=green": Border changes to green when the button is active.

Example with nth-child Pseudo-Class:

import { Box } from 'styled-proper';

const Item = ({ children }) => <Box.Div bg="white|:nthChild(2n)=black">{children}</Box.Div>;

function Component() {
    return (
        <div>
            {Array.from({ length: 10 }).map((_, i) => (
                <Item key={i}>{i}</Item>
            ))}
        </div>
    );
}

export default Component;

Description:

• bg="white": Default background is white.
• :nthChild(2n)=black: Background changes to black for all even-indexed elements.

List of Supported Pseudo-Classes:

Using Pseudo-Classes as Props

In styled-proper, you can use pseudo-classes as props to add dynamic styles. These must be written in camelCase (e.g., hover, focus, active, lastChild, nthChild, etc.). Additionally, you can combine multiple styles within a single prop using arrays and media queries.

Basic Example

You can directly add pseudo-classes in props by using square brackets [ ] to group styles:

<Button bg="black" color="white" hover="[bg=white;color=black]">
    click me
</Button>

Combining Pseudo-Classes Within the Same Prop:

<Button bg="black" color="white" hover=":active=[bg=white;color=black]">
    click me
</Button>

Adding Media Queries Within the Same Prop:

<Button bg="black" color="white" hover="[bg=red;color=white]|@sm=[bg=blue;color=black]">
    click me
</Button>

Combining Pseudo-Classes and Media Queries Within the Same Prop:

<Button bg="black" color="white" hover=":active=[bg=red;color=white]|:active@sm=[bg=blue;color=black]">
    click me
</Button>

If the pseudo-class requires parameters, they should be passed as an array, where the first element is the parameter, and the second element is the value:

import { Button } from 'styled-proper';

function Component() {
    return <Button nthChild={['2n', '[bg=black;color=white]|@sm=[bg=white;color=black]']}>click me</Button>;
}

export default Component;

List of Supported Pseudo-Classes as Props:

Support for Pseudo-Elements

You can also manage pseudo-elements like before, after, first-letter, first-line, selection, marker, placeholder, backdrop, and more. Their usage is similar to CSS: prepend :: followed by the pseudo-element name, then specify the desired value separated by =.

Pseudo-elements should be written in camelCase convention, such as before, after, firstLetter, firstLine, selection, marker, placeholder, backdrop, etc.

Example with the first-letter Pseudo-Element:

<Text.P color="black|::firstLetter=red">Hola</Text.P>

Example with the before Pseudo-Element

<Text.P position="relative|::before=absolute" content="::before=hi" top="::before=0" left="::before=0">
    Hola
</Text.P>

Example with Media Queries and Pseudo-Elements

<Text.P position="relative|::before=absolute" content="@md::before=hi" top="@md::before=0" left="@md::before=0">
    Hola
</Text.P>

List of Supported Pseudo-Elements:

Using Pseudo-Elements as Props

You can also use pseudo-elements as props.

Pseudo-elements must follow camelCase convention, such as before, after, firstLetter, firstLine, selection, marker, placeholder, backdrop, etc. To apply multiple styles to the same pseudo-element, wrap the styles in square brackets [] and separate each property-value pair with a semicolon ;.

Example::

<Button bg="black" color="white" position="relative" after="[position=absolute;content=hi;top=0;left=0]">click me</Button>

Adding Media Queries to the Same Prop:

<Button bg="black" color="white" position="relative" after="@sm=[position=absolute;content=hi;bg=red;right=0;left=0;top=100%]">
    click me
</Button>

List of Supported Pseudo-Elements as Props:

Support for Combinators

styled-proper supports the use of CSS combinators like >, +, ~, and `. To use them, prepend the symbol&` followed by the corresponding combinator and then the element to which the style is applied, very similar to CSS.

Example using the direct child combinator >

<Box.Div color="&>div=red">
    <div>1</div>
    <section>
        <div>2</div>
    </section>
    <div>3</div>
</Box.Div>

Example using the adjacent sibling combinator +

<div>
    <Box.Div color="&+div=red">1</Box.Div>
    <div>2</div>
    <div>3</div>
</div>

Example using the general sibling combinator ~

<div>
    <Box.Div color="&~div=red">1</Box.Div>
    <div>2</div>
    <div>3</div>
    <div>4</div>
    <div>5</div>
</div>

Example using the descendant combinator     

<Box.Div color="& p=red">
    <div>1</div>
    <div>
        <p>2</p>
    </div>
    <div>3</div>
</Box.Div>

List of Supported Combinators:

Using Combinators as Props

The use of combinators through props works by receiving an array as a parameter, where the first element is the combinator and the second is the styles:

Example using the direct child combinator > with the directChild prop:

<div>
    <Box.Div directChild={['div', '[color=red]']}>
        <div>1</div>
        <section>
            <div>2</div>
        </section>
        <div>3</div>
    </Box.Div>
</div>

Example using the adjacent sibling combinator + with the adjacentSibling prop:

<div>
    <Box.Div adjacentSibling={['div', '[color=red]']}>1</Box.Div>
    <div>2</div>
    <div>3</div>
</div>

Example using the general sibling combinator ~ with the generalSibling prop:

<div>
    <Box.Div generalSibling={['div', '[color=red]']}>1</Box.Div>
    <div>2</div>
    <div>3</div>
    <div>4</div>
    <div>5</div>
</div>

Example using the descendant combinator ` with thedescendant` prop:

<Box.Div descendant={['p', '[color=red]']}>
    <div>1</div>
    <div>
        <p>2</p>
    </div>
    <div>3</div>
</Box.Div>

API Reference

List of Components in styled-proper

List of Component Groups in styled-proper

List of Available Props in styled-proper

• Layout props

• Flex and Grid props

• Spacing props

• Typography props