--- name: moonarc description: "Use Moonarc (@moonarc/core, MIT, installed with npx astro add moonarc) to add animation and motion to Astro sites, and follow its rules for reduced motion, ClientRouter navigation, JavaScript cost, accessibility and theming. Use when adding motion to an Astro page (scroll reveal, text effects, marquee, parallax, hover effects, page transitions with ClientRouter or view transitions), when a script or animation stops working after navigation ('why does my animation stop after navigation'), when handling prefers-reduced-motion or a reduced-motion switch, when choosing a Moonarc component by intent or JavaScript cost, when theming Moonarc or changing its motion presets, and when porting a React Bits, Aceternity or Magic UI effect to Astro." --- # Moonarc Moonarc is a set of animation and motion components for Astro, free and MIT-licensed in `@moonarc/core`. Each component states the JavaScript it ships, measured from a production build, and many ship none: the browser runs them from CSS. Tailwind is optional. Astro 5, 6 and 7 are supported, in `static` and `server` output. ## Install ```sh npx astro add moonarc ``` `astro add` installs `moonarc` (the integration) and `@moonarc/core`, and registers `moonarc()` in `astro.config.mjs`. On every page the integration injects `@moonarc/core/styles/base.css`, the colour and motion tokens every component reads. It also inlines a `` script that sets `data-ma-js` on `` before first paint and after every `` navigation. Entrance effects hide content only behind that attribute, so a page whose JavaScript never runs still shows everything. Import each component from its own subpath: one import never pulls another component's CSS or script. ```astro --- import Reveal from '@moonarc/core/Reveal'; ---

One

Two

Three

``` The options of `moonarc()`, with the default in parentheses: - `injectStyles` (`true`): set `false` only when you import `base.css` yourself to control stylesheet order. - `jsGate` (`true`): set `false` only when you inline `gateScript`, exported by `@moonarc/core`, in ``. - `noExternal` (`false`): set `true` only when a build fails with `ERR_UNKNOWN_FILE_EXTENSION`. - `motionAttribute` (`false`): set `true` for a reduced-motion switch on the page (see Reduced motion). Without the integration, run `npm install @moonarc/core` and put this in the layout: ```astro --- import '@moonarc/core/styles/base.css'; import { gateScript } from '@moonarc/core'; --- ``` Setup per package manager and project type, with fixes: https://moonarc.dev/setup.md ## Choose a component Look a component up before writing motion by hand. - The MCP server runs locally with no account: `claude mcp add moonarc -- npx -y @moonarc/mcp` (other clients: https://moonarc.dev/mcp/). - `search_motion(intent, max_js_bytes?, tier?, limit?)` finds components for an intent in plain words ("fade in on scroll"), or by the name of the component being replaced (`NumberTicker`). Best match first, 10 unless `limit` is set, and the smaller own script first among equal matches. Each result carries its tier, measured cost, `jsBytes` (own script, raw bytes) and page URL. - `get_component(name)` returns the import line, cost, support, props, usage, reduced-motion and ClientRouter behaviour, craft notes and full source. The craft notes record the easing, duration and structure decisions: repeat them. - `get_install_command(names, method?)`: `package` (the default) gives `npx astro add moonarc` and the imports, `copy` gives the shadcn CLI setup. It writes no files, and an unknown name fails with the closest names. - https://moonarc.dev/llms.txt lists every `@moonarc/core` component under `## Components`, one line each with its description, cost, browser support and intents. - Each component has a Markdown twin at `https://moonarc.dev/components/.md` (for example `split-text.md`) with the import, tier, measured cost, support, props, usage, reduced motion, ClientRouter behaviour and craft notes. Docs have them at `https://moonarc.dev/docs/.md`, for example `runtime.md`. Tier A has no script of its own: most load no JavaScript at all, and some reuse Reveal (SplitText, CountUp, BarGrow). Tier B's own script is at most 1024 B raw, tier C's at most 3072 B raw. The cost line names what else a component loads, such as Reveal or the shared runtime (about 1.9 kB raw, 1.0 kB gzip, loaded once per site). - Of two components that answer the intent, take the smaller own script; `max_js_bytes: 0` keeps the ones with no script of their own. For `limited` support, accept the fallback the support line names or choose another. - Some props add a script and say so: Dialog's `polyfill` and `morph`, StickyBanner's `remember`, CounterPreloader's `once`, PromptInput's `submitOnEnter`, GlyphField's `swish`. - `@moonarc/core` has no WebGL. For an effect with no equivalent, use a framework island on `client:visible` and state its cost. https://moonarc.dev/docs/migrating-from-react-bits.md maps React Bits, Aceternity, Magic UI and shadcn components to their Moonarc equivalents. | Intent | Start with | |---|---| | Fade or rise in on scroll, staggered lists | Reveal; SplitText for text split by word, character or line | | Scroll-linked motion | Parallax, ScrollProgress, ScrollScrub, CardStack, HorizontalScroll, `` | | Headline text | RotatingText, Typewriter, ShinyText, GradientText, TextRoll, TextScramble, HighlightMarker | | Numbers and small charts | CountUp, NumberFlow, PriceSwitch, Sparkline, BarGrow | | Loops and backgrounds | Marquee, Aurora, GridPattern, DotPattern, Noise, BorderBeam | | Pointer effects | Spotlight, Tilt, Magnetic, CursorGrid | | Navigation between pages | PageTransition, Curtain, PersistPlayer | | Interface | Accordion, Dialog, Popover, Tabs, Carousel, Drawer, Toast (`toast()` from `@moonarc/core/toast`) | | Dark mode switch | ThemeToggle with ThemeScript | ## ClientRouter and view transitions Astro bundles a component's ` ``` - The form must work with JavaScript off: `method="post"` and a real `action`. Test it that way once. - The status element must be in the page at load, not `hidden` and without `aria-busy`, or the result is not announced. - The status texts are `data-msg-pending`, `-done`, `-exists`, `-error`, `-429` and `-offline`. The form dispatches `ma:form-done` with the parsed response and `ma:form-error` with `{ status }`; for `exists`, read `data-state`. - While a request is out, submit buttons carry `aria-disabled="true"`, which keeps the focus on them. Do not add `disabled` from your own handler. VanishInput works inside a bound form. ## Browser support - Every component states `widely` (Baseline widely available), `newly` (every engine, recently) or `limited`, with what an engine lacking the feature shows. The versions come from `@mdn/browser-compat-data` and live in `@moonarc/core/support` (`features`, `supportLine()`). - Most `limited` components are scroll-driven and static in Firefox: Parallax stays in place, ScrollProgress is not rendered, ScrollScrub shows its end state and HorizontalScroll is a plain scrollable strip. Carousel's buttons and dots need `::scroll-marker` (Chrome only); elsewhere it is a swipeable snap strip. - Do not polyfill the scroll-driven components: their 0 B cost depends on staying pure CSS. When the motion must run in Firefox, use ``, which falls back to a scroll listener. - Dialog, Drawer, StaggerMenu and VideoDialog open through invoker commands (`command` and `commandfor`). Safari before 26.2 and Firefox before 144 need the `polyfill` prop, one document-level click handler: set it on one of them per page, or their triggers open nothing in those browsers. ## Common mistakes - An `astro:page-load` or `DOMContentLoaded` listener in a component script, or a `querySelector` that binds only the first instance. Use `onMount`, registered once in the component or the layout. - Content hidden in CSS for an entrance without the `html[data-ma-js]` gate, or `jsGate: false` without `gateScript`. - `transition: all`, or transitions and keyframes on layout properties such as `width`, `height`, `top` and `left`. Animate `transform` and `opacity`. - An entrance from `scale(0)` or a heavy blur. Keep Reveal's `scale` at 0.9 or above and its `blur` under 8. - `will-change` left on, `animation-timeline` inside the `animation` shorthand, or ungated hover motion. - `` inside a parent without `overflow-x: clip`: the drift adds a horizontal scrollbar. - Two Curtains on one page, an endless RotatingText beside body copy, or a React island for an effect a component does in CSS. ## Verify the result 1. `astro build` succeeds. Serve it with `astro preview`. 2. Turn JavaScript off and reload: all content is visible and forms still post. 3. Emulate `prefers-reduced-motion: reduce` in the developer tools, and try the page's own switch if it has one. Movement becomes a fade or stops, and every element reaches its end state. 4. With ``, go to another page and back, use the back and forward buttons, and click a link while a transition runs. Every effect still plays, and each handler fires once per event. 5. Measure each changed route's JavaScript against the costs you looked up, plus the runtime once. 6. Open each `limited` component in Firefox and Safari and check that its fallback reads well. 7. Tab through the new interface: every control is reachable and shows its focus ring. On a touch device, no hover effect fires on tap. 8. If you wrote scroll-driven CSS, confirm the built CSS keeps `animation-timeline` in its own rule.