Sphere Album

Framer code component. Default export from SphereAlbum.tsx. Panel labels are shown in quotes where they differ from the prop name.

Cards

• items — The cards on the sphere. Add or remove rows to change how many there are; spacing redistributes itself, so you never have to rebalance by hand.

• items[].image — Cropped to fill the card. A row with no image shows a neutral gradient plate instead of a gap.

• items[].title — Used as the card's accessible label, and as image alt text when the image has none.

• items[].link — Where the card goes when clicked. Point it at a Framer page or an external URL. Leave it empty and the card becomes decorative but still spins.

• items[].width — Card width before perspective. Mixing portrait and landscape sizes is what gives the sphere its scattered rhythm.

• items[].height — Card height before perspective.

• openInNewTab — Opens every linked card in a new tab, with rel="noopener noreferrer" applied.

Motion

• radius — Sphere size as a share of the frame's shorter side, so it rescales with the frame instead of overflowing on phones.

• autoSpin — The drift it settles back into when nobody is touching it. Set to 0 to have it come to a complete stop.

• dragSpeed — How far the sphere turns per pixel dragged. At the default, a 100 px drag turns it about 33°.

• wheelSpeed — How hard a scroll pushes the spin. Scrolling adds to velocity rather than setting position, so it coasts like a flick.

• damping — How long a throw keeps going. Lower is heavier and stops sooner; 0.99 is nearly frictionless.

• captureWheel — On, the wheel rotates the sphere and the page stays put. Turn it off when the sphere sits inside a scrolling page and you'd rather the page won.

• enableZoom — Two-finger pinch, or ⌘/Ctrl + scroll, resizes the sphere between 0.62× and 1.7×.

• introMs — Cards bloom outward from the centre on load, staggered. Set to 0 to start fully formed.

Appearance

• depthFade — How transparent the far side goes. 0 keeps every card fully opaque and the sphere reads flatter.

• depthBlur — Blur at the very back. The front 45% of the sphere always stays sharp; blur ramps in quadratically behind that. Drop this to 0 first if you go past ~60 cards — it is the costliest property here.

• hoverLift — How far a hovered card eases toward the camera. 0 disables the effect.

• cardBackground — The mat behind each image. Visible as a border when Card inset is above 0.

• cardPadding — Mat width around the image. Set to 0 for edge-to-edge images with no frame.

• cardRadius — Corner radius on the card. The image inside is rounded to match, minus the inset.

• shadow — A soft drop shadow under every card. Turn it off on dark backgrounds, where it mostly muddies the edges.

Units

Panel numbers are scaled for comfortable slider ranges. Internally, rotation is measured in radians per 60 fps frame.

Fixed limits

Three limits are hardcoded rather than exposed, because they mark the edge of what stays controllable.

• Spin caps at 0.11 rad/frame (≈ 378°/s).

• Zoom is clamped to 0.62× – 1.7×.

• A press travelling 6 px or less counts as a tap, not a drag.

Types

interface Item {
    image?: { src: string; srcSet?: string; alt?: string }
    title?: string
    link?: string
    width: number
    height: number
}

interface SphereAlbumProps {
    items: Item[]
    openInNewTab: boolean

    radius: number
    autoSpin: number
    dragSpeed: number
    wheelSpeed: number
    damping: number
    captureWheel: boolean
    enableZoom: boolean
    introMs: number

    depthFade: number
    depthBlur: number
    hoverLift: number
    cardBackground: string
    cardPadding: number
    cardRadius: number
    shadow: boolean

    style?: React.CSSProperties
}

interface Item {
    image?: { src: string; srcSet?: string; alt?: string }
    title?: string
    link?: string
    width: number
    height: number
}

interface SphereAlbumProps {
    items: Item[]
    openInNewTab: boolean

    radius: number
    autoSpin: number
    dragSpeed: number
    wheelSpeed: number
    damping: number
    captureWheel: boolean
    enableZoom: boolean
    introMs: number

    depthFade: number
    depthBlur: number
    hoverLift: number
    cardBackground: string
    cardPadding: number
    cardRadius: number
    shadow: boolean

    style?: React.CSSProperties
}

interface Item {
    image?: { src: string; srcSet?: string; alt?: string }
    title?: string
    link?: string
    width: number
    height: number
}

interface SphereAlbumProps {
    items: Item[]
    openInNewTab: boolean

    radius: number
    autoSpin: number
    dragSpeed: number
    wheelSpeed: number
    damping: number
    captureWheel: boolean
    enableZoom: boolean
    introMs: number

    depthFade: number
    depthBlur: number
    hoverLift: number
    cardBackground: string
    cardPadding: number
    cardRadius: number
    shadow: boolean

    style?: React.CSSProperties
}