shutterclose

┌─────────────────────────────┐
│▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓│  ← slat 1
│▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓│  ← slat 2
│▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓│  ← slat 3
│         ┌────────┐          │
│         │ CLOSED │          │  ← sign
│         └────────┘          │
└─────────────────────────────┘

shutterclose covers any HTML element with smooth sliding slats and an optional customizable sign. Use it for modal overlays, content restrictions, maintenance screens, and creative UI moments. Ships with vanilla, React, and Vue bindings, full TypeScript types, and zero runtime dependencies.

Table of Contents

• Why shutterclose?
• Installation
• Quick Start
• Themes
• API Reference
  • Static API
  • Instance API
  • Options
  • React
  • Vue
• CDN / Browser Usage
• CSS Control
• Server-Side Rendering
• TypeScript
• Error Handling
• Contributing
• License

Why shutterclose?

• A genuinely unique effect. Animated, decelerating slats with overshoot give content a physical, mechanical roller-shutter feel that no generic fade or slide reproduces.
• Zero runtime dependencies. Pure JavaScript and CSS. Nothing else lands in your node_modules.
• Framework agnostic. First-class bindings for React and Vue, plus a vanilla API that works anywhere the DOM does.
• Tiny. 1.6 KB gzipped for the core, with separate subpath exports so you only ship the binding you use.

Installation

npm install shutterclose

pnpm add shutterclose

yarn add shutterclose

No build step? Load it straight from a CDN:

<script src="https://unpkg.com/shutterclose/dist/index.global.js"></script>
<link rel="stylesheet" href="https://unpkg.com/shutterclose/dist/shutterclose.css">

Quick Start

Vanilla

import ShutterClose from 'shutterclose'

// Close the element
await ShutterClose.close('.my-element', {
  sign: { title: 'CLOSED', theme: 'red' }
})

// Open it again
await ShutterClose.open('.my-element')

React

import { useState } from 'react'
import { ShutterClose } from 'shutterclose/react'

export function Panel() {
  const [shut, setShut] = useState(false)

  return (
    <ShutterClose isShut={shut} sign={{ title: 'CLOSED' }}>
      <p>Content here</p>
      <button onClick={() => setShut(!shut)}>Toggle</button>
    </ShutterClose>
  )
}

Vue

<script setup>
import { ref } from 'vue'
import { ShutterClose } from 'shutterclose/vue'

const shut = ref(false)
</script>

<template>
  <ShutterClose :is-shut="shut" :sign="{ title: 'CLOSED' }">
    <p>Content here</p>
    <button @click="shut = !shut">Toggle</button>
  </ShutterClose>
</template>

Themes

Six built-in sign themes ship out of the box:

🟠 default   🔵 blue   🟢 green
🟣 purple    🟡 gold   🔴 red

Apply a theme through any options object:

await ShutterClose.close('.modal', {
  sign: { title: 'CLOSED', theme: 'purple' }
})

API Reference

Static API

The default export exposes a static surface for one-off calls, global configuration, and a fluent builder.

ShutterClose.close

ShutterClose.close(target: Target, options?: ShutterCloseOptions): Promise<void>

Covers the target with the shutter animation. Resolves when the close animation completes.

await ShutterClose.close('.modal', {
  slats: 12,
  duration: 1.5,
  sign: { title: 'CLOSED', icon: '🔒', theme: 'red' }
})

ShutterClose.open

ShutterClose.open(target: Target): Promise<void>

Reveals a previously closed target. Resolves when the open animation completes.

await ShutterClose.open('.modal')

ShutterClose.target

ShutterClose.target(target: Target): ShutterCloseBuilder

Returns a reusable, chainable builder for declarative configuration.

const shutter = ShutterClose.target('.panel')
  .slats(16)
  .duration(1.8)
  .sign({ title: 'CLOSED', subtitle: 'Please try again later' })
  .onClose(() => console.log('closed'))
  .onOpen(() => console.log('opened'))

await shutter.close()
await shutter.open()

ShutterClose.configure

ShutterClose.configure(config: GlobalConfig): void

Sets global defaults shared by every instance and static call.

ShutterClose.configure({
  injectCSS: true,
  defaults: {
    slats: 10,
    duration: 1.5,
    sign: { title: 'MAINTENANCE' }
  }
})

Instance API

new ShutterClose(target: Target, options?: ShutterCloseOptions)

Construct an instance for fine-grained, stateful control over a single target.

const instance = new ShutterClose('.overlay', {
  slats: 12,
  sign: { title: 'CLOSED' }
})

await instance.close()
console.log(instance.isShut) // true
await instance.open()
instance.destroy()

Options

Every option is optional and merges over the configured global defaults.

SignConfig

React

Import bindings from shutterclose/react.

useShutterClose

useShutterClose(ref: RefObject<HTMLElement>, options?: ShutterCloseOptions)

import { useRef } from 'react'
import { useShutterClose } from 'shutterclose/react'

export function Panel() {
  const ref = useRef(null)
  const { close, open, toggle, isShut } = useShutterClose(ref, {
    slats: 12,
    sign: { title: 'CLOSED', theme: 'red' }
  })

  return (
    <div ref={ref}>
      <p>{isShut ? 'Closed' : 'Open'}</p>
      <button onClick={toggle}>Toggle</button>
    </div>
  )
}

<ShutterClose />

import { ShutterClose } from 'shutterclose/react'

<ShutterClose
  isShut={shut}
  slats={12}
  duration={1.5}
  sign={{ title: 'CLOSED', icon: '🔒', theme: 'red' }}
  onClosed={() => console.log('closed')}
  onOpened={() => console.log('opened')}
  className="container"
  style={{ maxWidth: 500 }}
>
  <h1>Content</h1>
</ShutterClose>

Vue

Import bindings from shutterclose/vue.

useShutterClose

useShutterClose(el: Ref<HTMLElement | null>, options?: ShutterCloseOptions)

<script setup>
import { ref } from 'vue'
import { useShutterClose } from 'shutterclose/vue'

const el = ref(null)
const { close, open, toggle, isShut } = useShutterClose(el, {
  slats: 12,
  sign: { title: 'CLOSED', theme: 'red' }
})
</script>

<template>
  <div ref="el">
    <p>{{ isShut ? 'Closed' : 'Open' }}</p>
    <button @click="toggle">Toggle</button>
  </div>
</template>

<ShutterClose />

<ShutterClose
  :is-shut="shut"
  :slats="12"
  :duration="1.5"
  :sign="{ title: 'CLOSED', icon: '🔒', theme: 'red' }"
  class="container"
  @closed="onClosed"
  @opened="onOpened"
>
  <h1>Content</h1>
</ShutterClose>

CDN / Browser Usage

The IIFE build exposes a global named ShutterClose. Drop in two tags and call it directly.

<!DOCTYPE html>
<html>
  <head>
    <link rel="stylesheet" href="https://unpkg.com/shutterclose/dist/shutterclose.css">
  </head>
  <body>
    <main id="app">
      <h1>Welcome</h1>
    </main>

    <script src="https://unpkg.com/shutterclose/dist/index.global.js"></script>
    <script>
      ShutterClose.close('#app', {
        slats: 16,
        duration: 1.5,
        sign: { title: 'CLOSED', theme: 'gold' }
      })
    </script>
  </body>
</html>

CSS Control

By default the core auto-injects its stylesheet into <head>, so no extra setup is needed.

import ShutterClose from 'shutterclose'
// Styles are injected automatically.

For full control over loading order or bundling, use the no-css entry and import the stylesheet yourself.

import ShutterClose from 'shutterclose/no-css'
import 'shutterclose/shutterclose.css'

ShutterClose.configure({ injectCSS: false })

The stylesheet exposes CSS custom properties for theming.

.sc-shutter {
  --sc-duration: 2s;
  --sc-easing: cubic-bezier(0.25, 0.46, 0.45, 0.94);
  --sc-start-y: -300%;
}

.sc-slat {
  background: linear-gradient(135deg, #333 0%, #444 100%);
}

Server-Side Rendering

The CSS injector guards on typeof document === 'undefined', so importing shutterclose is safe in SSR environments such as Next.js and Nuxt.

TypeScript

shutterclose is authored in strict TypeScript and ships complete .d.ts declarations for every entry point.

import type { ShutterCloseOptions, SignConfig, Theme } from 'shutterclose'
import ShutterClose from 'shutterclose'

const options: ShutterCloseOptions = {
  slats: 10,
  duration: 1.5,
  sign: { title: 'CLOSED', theme: 'red' }
}

await ShutterClose.close('.modal', options)

Exported types: ShutterCloseOptions, SignConfig, Theme, Target, GlobalConfig, and ShutterCloseTargetError.

Error Handling

A ShutterCloseTargetError is thrown when a selector matches no element.

import ShutterClose, { ShutterCloseTargetError } from 'shutterclose'

try {
  await ShutterClose.close('.does-not-exist')
} catch (err) {
  if (err instanceof ShutterCloseTargetError) {
    console.error('Target not found:', err.message)
  }
}

Contributing

Contributions are welcome. Open an issue or a pull request on GitHub. CI runs on Node 18 and 20 via GitHub Actions, and releases are managed with Changesets.

License

MIT. See LICENSE for details.