How to Customize the AuthLayout with a Logo and Background Image in refine-shadcn

To customize the AuthLayout in refine-shadcn, pass a React node to the logo prop and an image URL string to the backgroundImage prop, which renders an absolutely-positioned background layer and replaces the default SVG icon respectively.

The @ferdiunal/refine-shadcn-auth package provides a flexible AuthLayout component for authentication pages in Refine applications. This layout supports extensive customization through dedicated props that allow you to inject a custom logo and full-screen background image while maintaining the responsive two-pane design. According to the source code in the ferdiunal/refine-shadcn repository, you can override the default branding and visual appearance without modifying the component internals.

Understanding the AuthLayout API

The AuthLayout component exposes a TypeScript interface called AuthLayoutProps defined in packages/auth/src/components/auth-layout.tsx. This interface declares several optional props specifically designed for customization:

• logo – Accepts React.ReactNode to replace the default SVG icon displayed in the left pane
• backgroundImage – Accepts a string URL that is applied as a cover-sized background on the left pane
• title / subtitle – Optional text strings for branding messages
• className – Additional Tailwind CSS classes for the outer container

The component renders the background image through an absolutely-positioned div that covers the entire left section:

<div
  className="absolute inset-0 bg-zinc-900"
  style={{
    backgroundImage: backgroundImage ? `url(${backgroundImage})` : undefined,
    backgroundSize: "cover",
    backgroundPosition: "center",
  }}
/>

The logo prop is implemented with a conditional fallback that preserves the default SVG when no custom logo is provided:

{logo || (
  <svg …> … </svg>
)}

Implementing a Custom Logo

The logo prop accepts any valid React element, making it possible to use image tags, SVG components, or styled text. When provided, your custom element renders in place of the default icon.

Here is an example using a custom image component:

import { AuthLayout, LoginForm } from "@ferdiunal/refine-shadcn-auth";

function MyLogo() {
  return (
    <img
      src="/logo.svg"
      alt="My App"
      className="mr-2 h-8 w-8"
    />
  );
}

function LoginPage() {
  const handleLogin = (data) => {
    // your login logic …
  };

  return (
    <AuthLayout
      title="My App"
      subtitle="Welcome back"
      logo={<MyLogo />}
      className="min-h-screen"
    >
      <LoginForm onSubmit={handleLogin} loading={false} />
    </AuthLayout>
  );
}

You can also use inline JSX elements for simpler cases:

<AuthLayout
  logo={<span className="text-2xl font-bold text-white">Acme</span>}
  title="Acme Dashboard"
>
  {/* authentication form */}
</AuthLayout>

Adding a Full-Screen Background Image

The backgroundImage prop expects a string containing a valid image URL. This value is injected directly into the CSS background-image property of the left pane's overlay div. You can provide local paths, imported assets, or remote URLs.

Example with a local image asset:

import { AuthLayout } from "@ferdiunal/refine-shadcn-auth";

function LoginPage() {
  return (
    <AuthLayout
      title="Secure Sign In"
      subtitle="Welcome back to the platform"
      backgroundImage="/images/auth-bg.jpg"
      className="min-h-screen"
    >
      <LoginForm />
    </AuthLayout>
  );
}

Example using a remote image URL:

<AuthLayout
  backgroundImage="https://images.unsplash.com/photo-1519125323398-675f0ddb6308"
  className="h-screen w-full"
>
  {/* form content */}
</AuthLayout>

Complete Customization Example

Here is a comprehensive implementation combining both the custom logo and background image with full viewport coverage:

import { AuthLayout, LoginForm } from "@ferdiunal/refine-shadcn-auth";

function AppLogo() {
  return (
    <div className="flex items-center gap-2">
      <img 
        src="/assets/logo-dark.svg" 
        alt="Logo" 
        className="h-10 w-10 rounded-lg"
      />
      <span className="text-xl font-semibold text-white">MyPlatform</span>
    </div>
  );
}

export default function AuthenticationPage() {
  return (
    <AuthLayout
      logo={<AppLogo />}
      title="Welcome Back"
      subtitle="Sign in to continue to your dashboard"
      backgroundImage="/images/office-abstract.jpg"
      className="h-screen w-full bg-gray-50"
    >
      <LoginForm 
        onSubmit={(values) => console.log(values)}
        loading={false}
      />
    </AuthLayout>
  );
}

Summary

• AuthLayout accepts logo and backgroundImage props defined in packages/auth/src/components/auth-layout.tsx and exported from packages/auth/src/index.ts.
• The logo prop replaces the default SVG icon with any React element you provide, supporting images, SVGs, or styled text.
• The backgroundImage prop applies a cover-sized background image to the left pane via an absolutely-positioned div with inline styles.
• Use the className prop to control the outer container's height and responsive behavior, such as applying h-screen for full viewport coverage.

Frequently Asked Questions

Where is the AuthLayout component defined in the refine-shadcn repository?

The component is defined in packages/auth/src/components/auth-layout.tsx and re-exported from packages/auth/src/index.ts. These files contain the AuthLayoutProps interface and the rendering logic for the customizable left pane.

Can I use a remote HTTPS URL for the backgroundImage prop?

Yes, the backgroundImage prop accepts any valid image URL string. You can use remote URLs from CDNs, Unsplash, or other external sources, as well as local public paths or imported asset strings.

What happens if I omit the logo prop?

If you do not provide the logo prop, the component renders a default SVG icon as implemented in the fallback logic: {logo || (<svg … />)}. This ensures the layout remains functional without requiring custom branding.

Is the AuthLayoutProps interface exported for TypeScript consumers?

Yes, the interface is exported from the package, providing full type safety when extending or wrapping the AuthLayout component in your TypeScript applications.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}