--- title: "Next.js integration" description: "What @systhemaui/next adds over React, which components are Next twins, and best practices." requested_language: ar language: en translation_notice: "This page isn't translated yet" url: https://docs.systhema.app/ar/next/nextjs version: unreleased (main) docs_index: https://docs.systhema.app/ar/next/llms.txt --- > This page isn't translated yet. Showing English. `@systhemaui/next` provides the Systhema components for Next.js. It re-exports framework-independent React components and supplies twins that use `next/image`, `next/link` or pathname-aware listeners. Import from this package in Next.js applications; a few twin props intentionally differ from React. ## Design philosophy - When a component benefits from Next-specific behavior (such as `Image`, `Link`, `Button`, `Card`, `Chip`, `Header`, `Footer`), `@systhemaui/next` ships a custom Next implementation. - When a component doesn't need Next-specific behavior (such as `Section`, `Paragraph`, `Heading`, `Form*`, `SearchField`, `Separator`, `Stack`, `Columns`, `Accordion`), `@systhemaui/next` re-exports it from `@systhemaui/react`. Import components from `@systhemaui/next` in Next.js apps. Either you get the Next-aware version, or you get the React component verbatim. ```tsx import { Image, Link, Separator } from '@systhemaui/next' ``` ## Installation ```bash pnpm add @systhemaui/core @systhemaui/next ``` You don't need to install `@systhemaui/react` separately. `@systhemaui/next` depends on it transitively. Install it explicitly when importing React-specific implementations directly. Opt-in locale support bundles `next-intl`. See [Frontend locales](https://docs.systhema.app/ar/next/nextjs/locales.md). Never install `next-intl` yourself; a second copy conflicts with the bundled one. See [Manual installation](https://docs.systhema.app/ar/next/getting-started/installation/nextjs.md) for the full setup including registry access and Tailwind wiring. ## What this section covers This section covers only the Next-specific parts of `@systhemaui/next`: the provider, the gateway, the public origin helper and frontend locales. Props, subcomponents and examples of every component are on the [component pages](https://docs.systhema.app/ar/next/components.md), each with a "Next.js" section where the Next twin differs. ## Next.js twins The package keeps hand-maintained twins where Next.js changes rendering or navigation. With the current source: | Next.js behavior | Components | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Optimized images | [Image and Video](https://docs.systhema.app/ar/next/components/image.md), [Avatar](https://docs.systhema.app/ar/next/components/avatar.md), [QuoteAvatar](https://docs.systhema.app/ar/next/components/quote.md). Video's poster uses the image path. | | Links through `LinkHelper` | [Link](https://docs.systhema.app/ar/next/components/link.md), [Button](https://docs.systhema.app/ar/next/components/button.md), [Card](https://docs.systhema.app/ar/next/components/card.md), [Chip](https://docs.systhema.app/ar/next/components/chip.md), [Icon](https://docs.systhema.app/ar/next/components/icon.md), [Header](https://docs.systhema.app/ar/next/components/header.md) and [Footer](https://docs.systhema.app/ar/next/components/footer.md) navigation. | | Next media defaults | [MediaWrapper and overlays](https://docs.systhema.app/ar/next/components/media-wrapper.md) compose the Next media components. | | Images and links | [PostCard and HighlightCard](https://docs.systhema.app/ar/next/components/post-card.md), [PostsList](https://docs.systhema.app/ar/next/components/posts-list.md). | | Route-change handling | [Header](https://docs.systhema.app/ar/next/components/header.md) closes its mobile menu on pathname changes; [AosListener, ParallaxListener and ScrollClassesListener](https://docs.systhema.app/ar/next/components/listeners.md#nextjs) restart on pathname changes. | | Next listeners | [SysthemaProvider](https://docs.systhema.app/ar/next/nextjs/provider.md) mounts the Next-aware listeners. | `LinkHelper` wraps `next/link` and also handles same-page hashes; see [LinkHelper](https://docs.systhema.app/ar/next/components/utilities.md#linkhelper). Image behavior and sizing remain subject to the component's props; see [Image](https://docs.systhema.app/ar/next/components/image.md). ### Intentional API differences The twin drift test compares exported names, workspace-declared props and literal vocabularies against React. Its `ALLOWED` list records these intentional differences: - Next listeners take no `resetKey` prop and do not export the React listener props types. They restart through `usePathname()`. - Next adds `CardLinkProps` and `Card.link`, an alias of `Card.a`. Both link variants render through `next/link`. - Next exports `NextLinkChipProps` for `Chip.a`. - Next `PostCard` and `HighlightCard` render their own images, so they omit React's `renderImage` prop. They add `linked`; setting it to `false` disables their link wrapper. `PostsList` supplies Next image and link defaults while honoring caller render overrides. - React exports the internal helpers `resolveSamePageHash`, `withTagProxy`, `DisableAnimationsContext` and `useAnimationClasses` for twin implementations; the Next root does not re-export them. Use the component pages for complete props. Next and React share the token-derived variant vocabulary, but their inherited image and link library props can differ. ## Best practices - Import components from `@systhemaui/next` in Next.js apps, including re-exported components. - Put [SysthemaProvider](https://docs.systhema.app/ar/next/nextjs/provider.md) in the root layout to mount the config server and Next listeners. - Use `Card.link` for a clickable card, `Button.a` for a button-style link and `Icon.a` for a linked icon. - Supply appropriate image dimensions and `sizes`. Image disables optimization for GIF and SVG; use `unoptimized` when another format needs to bypass the optimizer. - Import runtime values from `@systhemaui/core/client` in client-reachable code. The core root reaches token JSON that cannot be tree-shaken. See [Client and server code](https://docs.systhema.app/ar/next/concepts/client-and-server.md). - Set `adminRouting: false` in the [gateway](https://docs.systhema.app/ar/next/nextjs/gateway.md) for a Next-only application. ## Related - [Browser support](https://docs.systhema.app/ar/next/concepts/browser-support.md) (including how `withSysthema()` drops Next's legacy polyfills) - [Next.js template](https://docs.systhema.app/ar/next/getting-started/templates/nextjs.md) - [Payload template](https://docs.systhema.app/ar/next/getting-started/templates/payload.md)