212 lines
6.7 KiB
Markdown
212 lines
6.7 KiB
Markdown
---
|
||
description: Next.js supports including CSS files as Global CSS or CSS Modules, using `styled-jsx` for CSS-in-JS, or any other CSS-in-JS solution! Learn more here.
|
||
---
|
||
|
||
# Built-In CSS Support
|
||
|
||
Next.js allows you to import CSS files from a JavaScript file.
|
||
This is possible because Next.js extends the concept of [`import`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) beyond JavaScript.
|
||
|
||
## Adding a Global Stylesheet
|
||
|
||
To add a stylesheet to your application, import the CSS file within `pages/_app.js`.
|
||
|
||
For example, consider the following stylesheet named `styles.css`:
|
||
|
||
```css
|
||
body {
|
||
font-family: 'SF Pro Text', 'SF Pro Icons', 'Helvetica Neue', 'Helvetica',
|
||
'Arial', sans-serif;
|
||
padding: 20px 20px 60px;
|
||
max-width: 680px;
|
||
margin: 0 auto;
|
||
}
|
||
```
|
||
|
||
Create a [`pages/_app.js` file](/docs/advanced-features/custom-app) if not already present.
|
||
Then, [`import`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) the `styles.css` file.
|
||
|
||
```jsx
|
||
import '../styles.css'
|
||
|
||
// This default export is required in a new `pages/_app.js` file.
|
||
export default function MyApp({ Component, pageProps }) {
|
||
return <Component {...pageProps} />
|
||
}
|
||
```
|
||
|
||
These styles (`styles.css`) will apply to all pages and components in your application.
|
||
Due to the global nature of stylesheets, and to avoid conflicts, you may **only import them inside [`pages/_app.js`](/docs/advanced-features/custom-app)**.
|
||
|
||
In development, expressing stylesheets this way allows your styles to be hot reloaded as you edit them—meaning you can keep application state.
|
||
|
||
In production, all CSS files will be automatically concatenated into a single minified `.css` file.
|
||
|
||
## Adding Component-Level CSS
|
||
|
||
Next.js supports [CSS Modules](https://github.com/css-modules/css-modules) using the `[name].module.css` file naming convention.
|
||
|
||
CSS Modules locally scope CSS by automatically creating a unique class name.
|
||
This allows you to use the same CSS class name in different files without worrying about collisions.
|
||
|
||
This behavior makes CSS Modules the ideal way to include component-level CSS.
|
||
CSS Module files **can be imported anywhere in your application**.
|
||
|
||
For example, consider a reusable `Button` component in the `components/` folder:
|
||
|
||
First, create `components/Button.module.css` with the following content:
|
||
|
||
```css
|
||
/*
|
||
You do not need to worry about .error {} colliding with any other `.css` or
|
||
`.module.css` files!
|
||
*/
|
||
.error {
|
||
color: white;
|
||
background-color: red;
|
||
}
|
||
```
|
||
|
||
Then, create `components/Button.js`, importing and using the above CSS file:
|
||
|
||
```jsx
|
||
import styles from './Button.module.css'
|
||
|
||
export function Button() {
|
||
return (
|
||
<button
|
||
type="button"
|
||
// Note how the "error" class is accessed as a property on the imported
|
||
// `styles` object.
|
||
className={styles.error}
|
||
>
|
||
Destroy
|
||
</button>
|
||
)
|
||
}
|
||
```
|
||
|
||
CSS Modules are an _optional feature_ and are **only enabled for files with the `.module.css` extension**.
|
||
Regular `<link>` stylesheets and global CSS files are still supported.
|
||
|
||
In production, all CSS Module files will be automatically concatenated into **many minified and code-split** `.css` files.
|
||
These `.css` files represent hot execution paths in your application, ensuring the minimal amount of CSS is loaded for your application to paint.
|
||
|
||
## Sass Support
|
||
|
||
Next.js allows you to import Sass using both the `.scss` and `.sass` extensions.
|
||
You can use component-level Sass via CSS Modules and the `.module.scss` or `.module.sass` extension.
|
||
|
||
Before you can use Next.js' built-in Sass support, be sure to install [`sass`](https://github.com/sass/sass):
|
||
|
||
```bash
|
||
npm install sass
|
||
```
|
||
|
||
Sass support has the same benefits and restrictions as the built-in CSS support detailed above.
|
||
|
||
### Customizing Sass Options
|
||
|
||
If you want to configure the Sass compiler you can do so by using `sassOptions` in `next.config.js`.
|
||
|
||
For example to add `includePaths`:
|
||
|
||
```js
|
||
const path = require('path')
|
||
|
||
module.exports = {
|
||
sassOptions: {
|
||
includePaths: [path.join(__dirname, 'styles')],
|
||
},
|
||
}
|
||
```
|
||
|
||
## Less and Stylus Support
|
||
|
||
To support importing `.less` or `.styl` files you can use the following plugins:
|
||
|
||
- [@zeit/next-less](https://github.com/zeit/next-plugins/tree/master/packages/next-less)
|
||
- [@zeit/next-stylus](https://github.com/zeit/next-plugins/tree/master/packages/next-stylus)
|
||
|
||
If using the less plugin, don't forget to add a dependency on less as well, otherwise you'll see an error like:
|
||
|
||
```bash
|
||
Error: Cannot find module 'less'
|
||
```
|
||
|
||
## CSS-in-JS
|
||
|
||
<details>
|
||
<summary><b>Examples</b></summary>
|
||
<ul>
|
||
<li><a href="https://github.com/zeit/next.js/tree/canary/examples/basic-css">Styled JSX</a></li>
|
||
<li><a href="https://github.com/zeit/next.js/tree/canary/examples/with-styled-components">Styled Components</a></li>
|
||
<li><a href="https://github.com/zeit/next.js/tree/canary/examples/with-styletron">Styletron</a></li>
|
||
<li><a href="https://github.com/zeit/next.js/tree/canary/examples/with-glamor">Glamor</a></li>
|
||
<li><a href="https://github.com/zeit/next.js/tree/canary/examples/with-cxs">Cxs</a></li>
|
||
<li><a href="https://github.com/zeit/next.js/tree/canary/examples/with-aphrodite">Aphrodite</a></li>
|
||
<li><a href="https://github.com/zeit/next.js/tree/canary/examples/with-fela">Fela</a></li>
|
||
</ul>
|
||
</details>
|
||
|
||
It's possible to use any existing CSS-in-JS solution.
|
||
The simplest one is inline styles:
|
||
|
||
```jsx
|
||
function HiThere() {
|
||
return <p style={{ color: 'red' }}>hi there</p>
|
||
}
|
||
|
||
export default HiThere
|
||
```
|
||
|
||
We bundle [styled-jsx](https://github.com/zeit/styled-jsx) to provide support for isolated scoped CSS.
|
||
The aim is to support "shadow CSS" similar to Web Components, which unfortunately [do not support server-rendering and are JS-only](https://github.com/w3c/webcomponents/issues/71).
|
||
|
||
See the above examples for other popular CSS-in-JS solutions (like Styled Components).
|
||
|
||
A component using `styled-jsx` looks like this:
|
||
|
||
```jsx
|
||
function HelloWorld() {
|
||
return (
|
||
<div>
|
||
Hello world
|
||
<p>scoped!</p>
|
||
<style jsx>{`
|
||
p {
|
||
color: blue;
|
||
}
|
||
div {
|
||
background: red;
|
||
}
|
||
@media (max-width: 600px) {
|
||
div {
|
||
background: blue;
|
||
}
|
||
}
|
||
`}</style>
|
||
<style global jsx>{`
|
||
body {
|
||
background: black;
|
||
}
|
||
`}</style>
|
||
</div>
|
||
)
|
||
}
|
||
|
||
export default HelloWorld
|
||
```
|
||
|
||
Please see the [styled-jsx documentation](https://github.com/zeit/styled-jsx) for more examples.
|
||
|
||
## Related
|
||
|
||
For more information on what to do next, we recommend the following sections:
|
||
|
||
<div class="card">
|
||
<a href="/docs/advanced-features/customizing-postcss-config.md">
|
||
<b>Customizing PostCSS Config:</b>
|
||
<small>Extend the PostCSS config and plugins added by Next.js with your own.</small>
|
||
</a>
|
||
</div>
|