# Getting started ## Installation Spectrum 2 in React Spectrum can be installed with your preferred package manager: ```bash npm install @react-spectrum/s2 ``` ## Configuring your bundler React Spectrum supports styling via [macros](https://parceljs.org/features/macros/), a new bundler feature that enables functions to run at build time. Currently, Parcel v2.12.0 and newer supports macros out of the box. When using other build tools, you can install a plugin to enable them. First, install `unplugin-parcel-macros` using your package manager: ```bash npm install unplugin-parcel-macros --dev ``` Then, configure your bundler to use the plugin: ### Webpack ```js // webpack.config.js const macros = require('unplugin-parcel-macros'); module.exports = { // ... plugins: [ macros.webpack() ] }; ``` ### Next.js ```js // next.config.js const macros = require('unplugin-parcel-macros'); // Create a single instance of the plugin that's shared between server and client builds. let plugin = macros.webpack(); module.exports = { webpack(config) { config.plugins.push(plugin); return config; } }; ``` ### Vite ```js // vite.config.js import macros from 'unplugin-parcel-macros'; export default { plugins: [ macros.vite() ] }; ``` ### Rollup ```js // rollup.config.js import macros from 'unplugin-parcel-macros'; export default { plugins: [ macros.rollup() ] }; ``` ### ESBuild ```js // build.mjs import {build} from 'esbuild'; import macros from 'unplugin-parcel-macros'; build({ plugins: [ macros.esbuild() ] }); ``` * Note that plugin order is important: `unplugin-parcel-macros` must run before other plugins like Babel. * You may also need to configure other tools such as TypeScript, Babel, ESLint, and Jest to support parsing import attributes. See [Usage with other tools](https://parceljs.org/features/macros/#usage-with-other-tools). * See the [examples folder](https://github.com/adobe/react-spectrum/tree/main/examples) for working setups with various build tools. * For details on optimizing the output CSS, see [CSS Optimization](styling.html#css-optimization). ## Setting up your app Wrap your app in an S2 `` component to load Spectrum 2 fonts for the user's locale and apply the appropriate Spectrum background layer for your app. When using S2 together with other versions of Spectrum, ensure that the S2 provider is the inner-most provider. ```tsx import {Provider} from '@react-spectrum/s2'; function App() { return ( {/* ... */} ); } ``` ### Optimizing full-page apps When building a full page S2 app that's not embedded within a larger page, import `@react-spectrum/s2/page.css` to apply the background color and color scheme to the `` element instead of the ``. This ensures that the page has styles even before your JavaScript loads. A `` is still necessary in addition to `page.css` in order to include the fonts, set the locale, etc. ```tsx // Apply S2 background to the element import '@react-spectrum/s2/page.css'; function App() { return ( {/* ... */} ); } ``` By default, this uses the `base` background layer. This can be customized by setting the `data-background` attribute on the `` element. ```tsx {/* ... */} ``` ### Server-side rendering When using SSR, the `` component can be rendered as the root `` element. The `locale` prop should always be specified to avoid hydration errors. `page.css` is not needed in this case. ```tsx {/* ... */} ``` ### Overriding the color scheme By default, React Spectrum follows the operating system color scheme setting, supporting both light and dark mode. The `colorScheme` prop can be set on `` to force the app to always render in a certain color scheme. ```tsx import {Provider} from '@react-spectrum/s2'; {/* your app */} ``` When using `page.css`, set the `data-color-scheme` attribute on the `` element. ```tsx {/* ... */} ``` ### Overriding the locale By default, React Spectrum uses the browser/operating system language setting for localized strings, date and number formatting, and to determine the layout direction (left-to-right or right-to-left). This can be overridden by setting the `locale` prop on the ``. ```tsx import {Provider} from '@react-spectrum/s2'; {/* your app */} ```