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

> Customize AuthLayout in refine-shadcn by adding a logo and background image. Easily personalize your authentication UI with this simple guide.

- Repository: [Ferdi ÜNAL/refine-shadcn](https://github.com/ferdiunal/refine-shadcn)
- Tags: how-to-guide
- Published: 2026-03-01

---

**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`](https://github.com/ferdiunal/refine-shadcn/blob/main/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:

```tsx
<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:

```tsx
{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:

```tsx
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:

```tsx
<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:

```tsx
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:

```tsx
<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:

```tsx
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`](https://github.com/ferdiunal/refine-shadcn/blob/main/packages/auth/src/components/auth-layout.tsx) and exported from [`packages/auth/src/index.ts`](https://github.com/ferdiunal/refine-shadcn/blob/main/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`](https://github.com/ferdiunal/refine-shadcn/blob/main/packages/auth/src/components/auth-layout.tsx)** and re-exported from **[`packages/auth/src/index.ts`](https://github.com/ferdiunal/refine-shadcn/blob/main/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.