ElvixProvider

Top-level context. Fetches the brand chord, factor config, and copy from elvix; pipes session state and the event channel to every nested <Elvix*> component.

Secured byelvix

Provider scope

Every nested elvix component reads brand + envelope from this provider. No prop drilling.

app/layout.tsx

import { ElvixProvider } from "@elvix.is/sdk/react";
import "@elvix.is/sdk/styles.css"; // REQUIRED. Without it every <Elvix*> surface renders unstyled.

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <ElvixProvider clientId={process.env.NEXT_PUBLIC_ELVIX_CLIENT_ID!}>
          {children}
        </ElvixProvider>
      </body>
    </html>
  );
}

Props

Prop	Type	Required	Default	Description
`clientId`	`string`	required	n/a	Your Application's client ID. Get it from Console, your Application, Credentials. Source from `NEXT_PUBLIC_ELVIX_CLIENT_ID` so client-side bundles can read it.
`locale`	`string`	optional	`"en"`	BCP-47 locale tag (`"en"`, `"de"`, `"pt-BR"`, `"uk"`). Flips every nested `<Elvix*>` component to the matching translation. Fifteen catalogs ship: en, de, es, fr, it, nl, pt-BR, pt-PT, tr, pl, cs, sv, el, ru, uk. English is bundled; the other fourteen lazy-fetch from `i18nBase`.
`i18nBase`	`string`	optional	`"https://elvix.is/api/v1/i18n/elvix"`	Override the translation CDN. Useful only when self-hosting translations off a different bucket.
`baseUrl`	`string`	optional	`"https://elvix.is"`	Override the elvix origin. Set this only for self-hosted instances or dev mirrors (e.g. `https://elvix.edvone.dev`).
`children`	`React.ReactNode`	required	n/a	Your app tree. The provider must wrap every `<Elvix*>` component and every hook (`useUserRoles`, `useElvixApp`, etc.).

clientId should come from NEXT_PUBLIC_ELVIX_CLIENT_ID. It is not a secret: Console-issued client IDs are safe to ship in client bundles. The provider uses it only to fetch the public brand and method bootstrap. Server-side verification still needs the user's session token.

Always import @elvix.is/sdk/styles.css alongside the provider. The SDK ships a single Tailwind-built stylesheet; without it every <Elvix*> surface renders unstyled (text-only, no brand chord, no card chrome).

Switching languages

Set locale to any of the fifteen production tags. Every nested <Elvix*> component switches to the matching catalog on the next render. The English catalog is bundled inside the SDK so the first paint is always instant; the other fourteen are fetched once per page from i18nBase and cached for the page lifetime.

app/layout.tsx (German UI)

<ElvixProvider
  clientId={process.env.NEXT_PUBLIC_ELVIX_CLIENT_ID!}
  locale="de"
>
  {children}
</ElvixProvider>

Missing translations gracefully fall back to English (the bundled catalog is the fallback chain root). The copy prop on <ElvixSignIn> still wins over locale catalogs for per-embed overrides.

Self-hosting and dev mirrors

Default: the provider talks to https://elvix.is. Override baseUrl only when pointing at a self-hosted instance or a dev mirror. Most apps never set this prop.

app/layout.tsx (self-hosted)

<ElvixProvider
  clientId={process.env.NEXT_PUBLIC_ELVIX_CLIENT_ID!}
  baseUrl={process.env.NEXT_PUBLIC_ELVIX_BASE_URL} // e.g. https://elvix.edvone.dev
>
  {children}
</ElvixProvider>

Disabling animations (0.7.12+)

Pass animated={false} on the provider to turn off mount + transition animations across EVERY nested <Elvix*> component in one move — <ElvixCard>'s brand trace, <ElvixSignInForm>'s step transitions, <ElvixDeactivate> / <ElvixLeave> / <ElvixAddressBook> / <ElvixSessions> / <ElvixExport> and the rest. Implemented via framer-motion's MotionConfig reducedMotion="always", so the cascade reaches every animation in the tree at zero per-component cost.

When animated is left at its default true, the provider broadcasts reducedMotion="user" instead — the SDK respects the browser's prefers-reduced-motion media query out of the box. Hosts get an accessibility-aware SDK by default and a hard kill-switch when they need it.

Use cases: screenshot / print surfaces, server-rendered emails, embedded checkouts, end-to-end tests where animation timing breaks assertions, and any UX research surface where motion noise muddies the read. Per-component animated props (e.g. <ElvixCard animated>) still override the cascade for one-off exceptions.

app/layout.tsx

import { ElvixProvider } from "@elvix.is/sdk/react";

// Disable every SDK animation everywhere inside this tree.
<ElvixProvider clientId="your-app" animated={false}>
  {children}
</ElvixProvider>

Reading the cascade from your own components

If you build custom surfaces that compose <Elvix*> and want them to honor the same flag, call useElvixAnimated() — returns true outside a provider (so the hook is safe to call unconditionally) and the provider's resolved value inside one. Compose with a local override the same way the SDK does:

components/your-pane.tsx

import { useElvixAnimated } from "@elvix.is/sdk/react";

function YourPane({ animated: animatedProp }: { animated?: boolean }) {
  const providerAnimated = useElvixAnimated();
  const animated = animatedProp ?? providerAnimated;
  // ... use `animated` to gate framer-motion initial/animate/transition
}

ElvixCard

The chrome every SDK lives in. Brand-tinted border, Secured-by-elvix badge breakpoint, scrollable body + pinned footer pattern.

Read

Ban / pause / delete watcher

Mount once in any authenticated layout. When the user's membership flips off active, the watcher paints a full-screen blocking modal with a 9-second countdown, then signs them out and redirects.