Sprite Background

A background image renderer for single sprite-sheets

1
import { SpriteBackground } from "@/components/ui/pxl/sprite-background";
2

3
export default function SpriteBackgroundPreview() {
4
  return (
5
    <div className="w-full min-h-23 flex items-center justify-center">
6
      <SpriteBackground
7
        src="https://raw.githubusercontent.com/pxl-ui/registry/main/app/public/sprites/tiny_chick.png"
8
        columns={4}
9
        rows={1}
10
        animation="Idle"
11
      />
12
    </div>
13
  );
14
}

Installation

Command
Manual

pnpm dlx shadcn@latest add pxl-ui/registry/sprite-background

Copy and paste the following code into your project.

1
import { cva, type VariantProps } from "class-variance-authority";
2
import type { ComponentProps } from "react";
3

4
import { cn } from "@/lib/utils";
5

6
const spriteBackgroundVariants = cva("sprite-sheet", {
7
  variants: {
8
    size: {
9
      default: "size-24",
10
      xs: "size-8",
11
      sm: "size-12",
12
      md: "size-16",
13
      lg: "size-24",
14
      xl: "size-32",
15
    },
16
    columns: {
17
      default: "sprite-cols-4",
18
      2: "sprite-cols-2",
19
      4: "sprite-cols-4"
20
    },
21
    rows: {
22
      default: "sprite-rows-1",
23
      1: "sprite-rows-1",
24
      2: "sprite-rows-2"
25
    },
26
    animation: {
27
      default: "",
28
      Idle: "",
29
      Action: "",
30
      Sleep: "",
31
    },
32
  },
33
  defaultVariants: {
34
    size: "default",
35
    columns: "default",
36
    rows: "default",
37
    animation: "default",
38
  },
39
  compoundVariants: [
40
    {
41
      columns: 4,
42
      rows: 1,
43
      animation: "Idle",
44
      className: "sprite-animate-[0,1,2,3] sprite-duration-[500ms]"
45
    },
46
    {
47
      columns: 2,
48
      rows: 2,
49
      animation: "Idle",
50
      className: "sprite-animate-[0,1] sprite-duration-[1000ms]"
51
    }
52
  ]
53
});
54

55
export function SpriteBackground({
56
  animation,
57
  className,
58
  columns,
59
  rows,
60
  size,
61
  src,
62
}: VariantProps<typeof spriteBackgroundVariants> &
63
  ComponentProps<"div"> & {
64
    src: string;
65
  }) {
66
  return (
67
    <div
68
      className={cn(spriteBackgroundVariants({
69
        animation,
70
        columns,
71
        rows,
72
        size
73
      }), className)}
74
      style={{
75
        backgroundImage: `url("${src}")`,
76
      }}
77
    />
78
  );
79
}

Update the import paths to match your project setup.

Usage

import { SpriteBackground } from "@/components/ui/pxl/sprite-background"

<SpriteBackground
  src="https://raw.githubusercontent.com/pxl-ui/registry/main/app/public/sprites/tiny_chick.png"
  columns={4}
  rows={1}
  animation="Idle"
/>

Sizes

ExtraSmall

Small

Medium

Large

ExtraLarge

1
import { Fragment } from "react";
2

3
import { SpriteBackground } from "@/components/ui/pxl/sprite-background";
4
import type { SpriteSize } from "@/lib/pxl/sprite";
5

6
export default function Sizes() {
7
  const sizes: Record<SpriteSize, string> = {
8
    xs: "ExtraSmall",
9
    sm: "Small",
10
    md: "Medium",
11
    lg: "Large",
12
    xl: "ExtraLarge",
13
  };
14

15
  return (
16
    <div className="w-full min-h-92 flex flex-col gap-2.5 items-start justify-center">
17
      <div>
18
        {Object.entries(sizes).map(([size, label]) => (
19
          <Fragment key={size}>
20
            <h2>{label}</h2>
21
            <SpriteBackground
22
              src="https://raw.githubusercontent.com/pxl-ui/registry/main/app/public/sprites/tiny_chick.png"
23
              animation="Idle"
24
              size={size as SpriteSize}
25
              columns={4}
26
              rows={1}
27
            />
28
          </Fragment>
29
        ))}
30
      </div>
31
    </div>
32
  );
33
}