# astro-emotion

> Use Emotion CSS to style your Astro site.

Latest version **3.0.1** (published 2025-09-18) · Public Domain license · 0 weekly downloads

## Install

```sh
npm install astro-emotion
pnpm add astro-emotion
yarn add astro-emotion
bun add astro-emotion
```

## Health

**Score 45/100 (D)** — status: stable.

Positive: esm support; no vulnerabilities; has provenance.

Warnings: low downloads; no types.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 3.0.1 |
| Published | 2025-09-18 |
| First published | 2023-12-01 |
| Weekly downloads | 0 |
| License | Public Domain |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 3 |
| Unpacked size | 15.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 160 |
| Author | Arsh |
| Maintainers | arshx |
| Keywords | withastro, astro-component |

## Links

- npm: https://www.npmjs.com/package/astro-emotion
- Repository: https://github.com/lilnasy/gratelets
- Homepage: https://github.com/lilnasy/gratelets/tree/main/packages/emotion
- Issues: https://github.com/lilnasy/gratelets/issues
- npm.io page: https://npm.io/package/astro-emotion

## Dependencies (3)

- [acorn-walk](https://npm.io/package/acorn-walk.md) 8
- [@emotion/css](https://npm.io/package/@emotion/css.md) 11
- [magic-string](https://npm.io/package/magic-string.md) 0.30

## Recent versions

- 3.0.1 (latest) — 2025-09-18
- 3.0.0 — 2024-12-09
- 2.0.0 — 2024-11-04
- 1.0.1 — 2023-12-01
- 1.0.0 — 2023-12-01

## README

# astro-emotion 👩‍🎤

This **[Astro integration][astro-integration]** brings [Emotion's](https://emotion.sh/docs/introduction) CSS rules to every `.astro` file and [framework component](https://docs.astro.build/en/core-concepts/framework-components/) in your project.

- <strong>[Why Emotion](#why-emotion)</strong>
- <strong>[Installation](#installation)</strong>
- <strong>[Usage](#usage)</strong>
- <strong>[Configuration](#configuration)</strong>
- <strong>[Examples](#examples)</strong>
- <strong>[Troubleshooting](#troubleshooting)</strong>
- <strong>[Contributing](#contributing)</strong>
- <strong>[Changelog](#changelog)</strong>

## Why Emotion?

Emotion lets you colocate CSS rules with your JSX instead of having them in a separate file. You might find it easier to write and maintain your styles using vanilla CSS properties!

`astro-emotion` does not require a runtime to be sent to the browser or your SSR app. Instead, it works by reading your components' source code, and creating stylesheets from it during build-time. This approach is often called "macros" or "runes" in other ecosystems. This integration offers two macros - `css`, and `injectGlobal`. The `css` template tag processes CSS properties and compiles them into a scoped class name, which you can add to your HTML elements. The `injectGlobal` template tag lets you add global styles to the current page.

Emotion is also a great choice to add styles to React, Preact, or Solid components, which don't support a `<style>` tag in the component file.

## Installation

### Manual Install

First, install the `astro-emotion` package using your package manager. If you're using npm or aren't sure, run this in the terminal:

```sh
npm install astro-emotion
```
Note: you do not need to install emotion separately. Installing this integration alone is sufficient.

Next, apply this integration to your `astro.config.*` file using the `integrations` property:

```diff lang="js" "emotion()"
  // astro.config.mjs
  import { defineConfig } from 'astro/config';
+ import emotion from 'astro-emotion';

  export default defineConfig({
    // ...
    integrations: [emotion()],
    //             ^^^^^^^^^
  });
```

## Usage

Once the integration is installed and added to the configuration file, you can import the `css` and `injectGlobal` macros from the `"astro:emotion"` namespace.

```ts
// src/components/react.tsx
import { css, injectGlobal } from "astro:emotion"

injectGlobal`
  body {
    margin: 0;
    padding: 0;
  }
`

export default function () => (
  <div
    className={css`
      background-color: hotpink;
      &:hover {
        color: white;
      }
    `}
  >
    This has a hotpink background.
  </div>
)
```

## Limitations

Since the integration acts only during build-time, it cannot process dynamic styles. For example, this will not work:

```tsx
import { css } from "astro:emotion"
const margin = "1rem"
const className = css`margin: ${margin};`
const element = <div className={className} />

```

Instead use CSS variables for values that may change:

```tsx
import { css } from "astro:emotion"
const margin = "1rem"
const className = css`margin: var(--margin);`
const element = <div style={{ "--margin": margin }} className={className} />
```

## Troubleshooting

For help, check out the `Discussions` tab on the [GitHub repo](https://github.com/lilnasy/gratelets/discussions).

## Contributing

This package is maintained by [lilnasy](https://github.com/lilnasy) independently from Astro. The integration code is located at [packages/emotion/integration.ts](https://github.com/lilnasy/gratelets/blob/main/packages/emotion/integration.ts). You're welcome to contribute by opening a PR or submitting an issue!

## Changelog

See [CHANGELOG.md](https://github.com/lilnasy/gratelets/blob/main/packages/emotion/CHANGELOG.md) for a history of changes to this integration.

[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/

---
_Source: https://npm.io/package/astro-emotion · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._