Built with ❤️ by @Kingrashy12. Licensed under the Apache License 2.0.
- Installation
- Features
- Why Use StylrJS
- NextJs Setup
- Usage
- Using With Types
- Exported Types
- API Reference
- License
- Issues
- Contributing
- Acknowledgments
npm:
npm install stylrjsyarn:
yarn add stylrjs- Intuitive API for easy styling
- Type-safe styling with TypeScript support
- Performance optimized with minimal runtime overhead
- Customizable and extendable
- Automatic vendor prefixing for cross-browser compatibility
- No dependencies on external libraries
- Filters invalid props from being passed to the DOM
- Supports dynamic styling based on props
StylrJS offers a modern, efficient, and intuitive approach to styling your applications. Here are some key reasons to choose StylrJS:
- Props not recognized by React (e.g.,
variant) are automatically converted into validdata-*attributes (e.g.,data-variant), ensuring clean and valid HTML while preventing unnecessary props from being passed to the DOM.
- Fully compatible with TypeScript, providing type definitions for all HTML elements.
- Supports type-safe custom props, ensuring a seamless development experience.
- If you're familiar with CSS and JavaScript, getting started with StylrJS is straightforward.
- Leverages tagged template literals, making it easy to write styles in a familiar syntax.
- Encourages styling directly within components, enhancing cohesion and maintainability.
- Avoids global CSS conflicts by scoping styles to specific components.
- Easily style third-party or custom React components while preserving their original props.
- Integrates seamlessly into both functional and class components.
- Write dynamic styles using props, enabling conditional and reusable styles.
- Simplifies styling logic by co-locating styles with components.
- Optimized for performance, ensuring minimal runtime overhead.
- Produces highly efficient, scoped CSS without bloating your app.
- StylrJS currently uses a
StylrJsRegistrycomponent to collect and render styles for server-side rendering (SSR). - This approach ensures styles are correctly included during the initial server-side render of your application.
- Coming Soon: The registry process will be handled automatically, making SSR integration even more seamless.
StylrJs comes with a CLI tool to streamline setting up your project with Next.js.
- Initialize StylrJs Registry
Run the following command to generate the required setup files:
npx stylrjs initThis command will create a StylrJsRegistry component and add it to your project at lib/registry.js or lib/registry.tsx file.
- Import StylrJsRegistry into your root layout
Next, import the StylrJsRegistry component in your layout.js or layout.tsx file:
-
app/layoutfor App Router -
src/layoutfor Pages Router -
TypeScript
import StylrJsRegistry from '@/lib/registry';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en" >
<body>
<StylrJsRegistry>{children}</StylrJsRegistry>
</body>
</html>
);
}- JavaScript
import StylrJsRegistry from '@/lib/registry';
export default function RootLayout({ children }) {
return (
<html lang="en">
<body>
<StylrJsRegistry>{children}</StylrJsRegistry>
</body>
</html>
);
}Note: When using the
styledAPI in the Next.js App Router, you must include the'use client'directive at the top of the file. No need to worry about style glitches—StylrJs ensures smooth styling across your app.
Basic example:
import { styled } from "stylrjs";
const Button = styled("button")`
background-color: blue;
color: white;
padding: 10px 20px;
border: none;
cursor: pointer;
`;
export default Button;StylrJS is fully compatible with TypeScript and provides type definitions for all HTML elements. Here's how you can use it effectively with types:
- Basic usage with inferred types:
import { styled } from "stylrjs";
const Button = styled("button")`
background-color: blue;
color: white;
padding: 10px 20px;
`;
// Button will automatically have the correct HTML button element props- Extending HTML element props:
import { styled, ButtonProps } from "stylrjs";
interface CustomButtonProps extends ButtonProps {
isActive?: boolean;
}
const Button = styled<CustomButtonProps>("button")`
background-color: ${(props) => (props.isActive ? "blue" : "gray")};
color: white;
padding: 10px 20px;
`;
// Usage
<Button isActive onClick={() => console.log("Clicked!")}>
Click me
</Button>;- Using with custom components:
import { styled } from "stylrjs";
import { ComponentProps } from "react";
const CustomComponent = ({
className,
children,
}: {
className?: string;
children: React.ReactNode;
}) => <div className={className}>{children}</div>;
// Use ComponentProps to inherit props from the custom component.
// Only extend props when adding style to an existing component.
interface StyledCustomComponentProps
extends ComponentProps<typeof CustomComponent> {
backgroundColor?: string;
}
const StyledCustomComponent = styled<StyledCustomComponentProps>(
CustomComponent
)`
background-color: ${(props) => props.backgroundColor || "white"};
padding: 20px;
`;
// Usage
<StyledCustomComponent backgroundColor="lightblue">
Custom styled component
</StyledCustomComponent>;- Type Safety: Prevent runtime errors with compile-time checks.
- Autocomplete Support: Get IntelliSense for HTML attributes and custom props.
- Enhanced Readability: Clearly define props for components, improving code maintainability.
StylrJS exports type definitions for all HTML elements. You can import these types from stylrjs. Here's a list of all exported types:
ButtonPropsAnchorPropsInputPropsTextareaPropsSelectPropsFormPropsImagePropsDivPropsSpanPropsParagraphPropsListItemPropsUnorderedListPropsOrderedListPropsTablePropsTableRowPropsTableCellPropsHeaderPropsLabelPropsArticlePropsSectionPropsNavPropsAsidePropsFooterPropsMainPropsAddressPropsAudioPropsVideoPropsCanvasPropsEmbedPropsIFramePropsObjectPropsPicturePropsSourcePropsTrackPropsDetailsPropsDialogPropsMenuPropsSummaryPropsDataPropsTimePropsVarPropsCodePropsPrePropsBlockquotePropsCitePropsDelPropsInsPropsKbdPropsMarkPropsQPropsSPropsSampPropsStrongPropsSubPropsSupPropsWbrPropsAreaPropsMapPropsColPropsColGroupPropsCaptionPropsTHeadPropsTBodyPropsTFootPropsThPropsFieldsetPropsLegendPropsDatalistPropsOptGroupPropsOptionPropsOutputPropsProgressPropsMeterPropsHtmlPropsHeadPropsBasePropsMetaPropsScriptPropsNoScriptPropsTemplatePropsSlotProps
You can use these types to extend the props of your styled components or to type-check your components. For example:
import { styled, ButtonProps } from "stylrjs";
interface CustomButtonProps extends ButtonProps {
isActive?: boolean;
}
const Button = styled<CustomButtonProps>("button")`
// ... styles ...
`;This ensures type safety and provides autocompletion for all standard HTML attributes plus your custom props.
The styled function is the core function for creating styled components. It takes a tag name as an argument and returns a new component that applies the styles to the specified HTML element.
tag: keyof JSX.IntrinsicElements- The HTML tag to be styled.
React.FC<any>- A new React functional component that renders the styled element.
This project is licensed under the Apache License 2.0. See the LICENSE file for more details.
If you find any issues, please open an issue on the GitHub repository.
We welcome contributions to StylrJS! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request.
For more detailed information on how to contribute, please read our CONTRIBUTING.md guide.