🔒 Feature Lock

Contextual feature locking for React that doesn't interrupt flow

✨ What is Feature Lock?

Feature Lock is a collection of React components for building contextual upgrade experiences. Instead of redirecting users to pricing pages, show upgrade prompts directly on the features they want to unlock.

The Problem

Traditional paywalls interrupt the user experience:

Click "Export Report" → Redirected to pricing page
Context is lost
User forgets why they clicked
Lower conversion rates

The Solution

Feature Lock keeps users in context:

Click "Export Report" → Overlay appears on the locked feature
Clear upgrade prompt right where they need it
User understands the value immediately
Higher conversion rates

📦 Components

BlurWrapper

The flagship component that blurs locked features and guides users to upgrade—without breaking their flow.

Quick Start

npx shadcn@latest add https://feature-lock.griffen.codes/r/blur-wrapper

Basic Usage

import { useState } from "react"
import BlurWrapper from "@/components/blurWrapper/blur-wrapper"

export function LockedFeature() {
  const [locked, setLocked] = useState(true)

  async function handleUpgrade() {
    await fetch("/api/upgrade", { method: "POST" })
    setLocked(false)
  }

  return (
    <BlurWrapper
      isBlurred={locked}
      onConfirm={handleUpgrade}
      onUnblur={() => setLocked(false)}
    >
      <YourPremiumContent />
    </BlurWrapper>
  )
}

View Full BlurWrapper Documentation →

PaywallBanner

Dismissible announcement banner that spotlights new or locked functionality, provides upgrade CTAs, and respects user choice with optional local persistence.

Async primary & secondary actions with loading/error states
Variants for upgrade, info, success, and warning messages
Optional storageKey to remember dismissals across visits

Install directly into your project:

npx shadcn@latest add https://feature-lock.griffen.codes/r/paywall-banner

FeatureTooltip

Inline tooltip for gently nudging upgrades without interrupting users. Ideal for inline icons, disabled buttons, or table cells.

Accessible Radix tooltip trigger on hover/focus
Optional CTA (link or async action) with pending/error states
Highlight list for feature value props

Install it with one command:

npx shadcn@latest add https://feature-lock.griffen.codes/r/feature-tooltip

UpgradeModal

Standalone upgrade dialog that compares plans, highlights value props, and routes users to checkout flows.

Supports async CTAs and links per plan with pending/error states
Automatically adapts layout for one, two, or three plan offerings
Includes fine print, support contact callout, and recommended badge styling

Install directly:

npx shadcn@latest add https://feature-lock.griffen.codes/r/upgrade-modal

UsageProgress

Quota dashboards that show consumption trends, warn before limits, and route users to upgrade flows.

Per-track badges, trend arrows, and progress bars
Summary banner with plan unlock messaging and CTA row
Async upgrade handler with error feedback and secondary actions

Add it to your project:

npx shadcn@latest add https://feature-lock.griffen.codes/r/usage-progress

Coming Soon

More components - Additional monetization patterns coming soon

🚀 Quick Start

Prerequisites

Make sure you have a Next.js project with shadcn/ui set up:

npx shadcn@latest init

Installation

Install the BlurWrapper component:

npx shadcn@latest add https://feature-lock.griffen.codes/r/blur-wrapper

This installs:

BlurWrapper component
Required shadcn/ui components (Button, Dialog)
All necessary dependencies

Your First Feature Lock

import { useState } from "react"
import BlurWrapper from "@/components/blurWrapper/blur-wrapper"

export function Dashboard() {
  const [analyticsLocked, setAnalyticsLocked] = useState(true)

  return (
    <BlurWrapper
      isBlurred={analyticsLocked}
      overlayMode="inline"
      inlinePosition="centerCenter"
      onConfirm={async () => {
        await upgradeUserPlan()
      }}
      onUnblur={() => setAnalyticsLocked(false)}
    >
      <AdvancedAnalytics />
    </BlurWrapper>
  )
}

🎯 BlurWrapper Features

🎨 Two Overlay Modes

Dialog Mode - Full-screen modal for critical upgrade decisions Inline Mode - Contextual overlay positioned directly on locked content

⚡ Key Features

Async-Ready: Built with React 19's useTransition for seamless async operations
Secondary Actions: Optional secondary button for "Learn More" or "Contact Sales" actions
Custom Icons: Replace the default Lock icon with any Lucide icon
Accessible by Default: Focus blocking with inert, screen reader announcements, error focus management
Flexible Positioning: 9 position options for inline overlays
Custom Overlays: Full control with render props
Error Handling: Built-in error states with automatic focus management

See the component README for detailed examples and API documentation.

📚 BlurWrapper Documentation

For complete API documentation, advanced examples, and implementation patterns, see:

Component README - Full technical reference
Live Documentation - Interactive examples

For more examples including custom error handling, controlled state, and advanced patterns, see the component README.

🏗️ Built With

React 19 - UI library with useTransition
Next.js 14+ - React framework
TypeScript - Type safety
Tailwind CSS - Styling
shadcn/ui - Component library
Radix UI - Accessible primitives

🎯 When to Use Feature Lock

✅ Great For

Gating premium features (analytics, exports, advanced tools)
Contextual upgrade prompts in dashboards
Freemium SaaS products
Trial limitations
Feature-based pricing tiers

⚠️ Not Recommended For

Full page paywalls (use traditional pricing pages)
Content behind authentication (use proper auth)
Critical security features (don't rely on client-side blur)

🎨 Component Registry

Feature Lock components are distributed via a ShadcnUI-compatible registry. This means:

✅ Easy Installation - One command installs everything ✅ Automatic Dependencies - No manual package.json editing ✅ Version Management - Registry tracks component versions ✅ Full Source Code - Components installed in your project (not node_modules)

Available Components

Component	Status	Command
BlurWrapper	✅ Stable	`npx shadcn@latest add https://feature-lock.griffen.codes/r/blur-wrapper`
PaywallBanner	✅ New	`npx shadcn@latest add https://feature-lock.griffen.codes/r/paywall-banner`
FeatureTooltip	✅ New	`npx shadcn@latest add https://feature-lock.griffen.codes/r/feature-tooltip`
UpgradeModal	✅ New	`npx shadcn@latest add https://feature-lock.griffen.codes/r/upgrade-modal`
UsageProgress	✅ New	`npx shadcn@latest add https://feature-lock.griffen.codes/r/usage-progress`
AgeGate	✅ New	`npx shadcn@latest add https://feature-lock.griffen.codes/r/age-gate`

Registry API

The registry exposes these endpoints:

GET /api/registry - List all components
GET /api/registry/r/:name - Get specific component

Learn more about the registry →

📊 Analytics

This project includes Vercel Analytics integration to track:

Component installations
Documentation engagement
Demo interactions
Conversion funnels

View Analytics Guide →

🤝 Contributing

We love contributions! Whether you want to:

🐛 Report bugs
✨ Suggest features
📝 Improve documentation
💻 Submit code
🎨 Design new components

Check out our Contributing Guide →

Development Setup

# Clone the repo
git clone https://github.com/gfargo/feature-lock.git
cd feature-lock

# Install dependencies
npm install

# Start dev server
npm run dev

# Generate registry
npm run gen:registry

🐛 Troubleshooting

Import Errors

Verify your tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"]
    }
  }
}

Blur Not Visible

Ensure content has non-transparent background:

<BlurWrapper isBlurred={locked}>
  <div className="bg-white dark:bg-slate-900">
    {/* Content */}
  </div>
</BlurWrapper>

Overlay Not Showing

Check that showOverlayOnBlur is not false:

<BlurWrapper
  isBlurred={locked}
  showOverlayOnBlur={true} // Default
>
  <Content />
</BlurWrapper>

View Full Troubleshooting Guide →

📄 License

See LICENSE for details.

🙏 Acknowledgments

shadcn - For the amazing component library and CLI architecture
Radix UI - For accessible, unstyled primitives
Vercel - For hosting and analytics
React Team - For useTransition and concurrent features

🔗 Links

Live Demo - Try it yourself
Documentation - Full API reference
Blog Post - Design philosophy
GitHub Issues - Report bugs
Discussions - Ask questions

📈 Project Roadmap

Current (v1.0)

✅ BlurWrapper component
✅ PaywallBanner component
✅ FeatureTooltip component
✅ UpgradeModal component
✅ UsageProgress component
✅ Dialog and inline modes
✅ Async handling with useTransition
✅ Full accessibility support
✅ Component registry
✅ Documentation site
✅ Analytics integration

Coming Soon (v1.1)

🚧 Additional positioning options
🚧 Animation customization

Future (v2.0)

🔮 Internationalization (i18n)
🔮 Vue and Svelte versions
🔮 Storybook documentation

⭐ Show Your Support

If Feature Lock helps your project, please give it a star on GitHub! It helps others discover the project.

Built with ❤️ by Griffen Labs

Website • GitHub • Twitter

Name		Name	Last commit message	Last commit date
Latest commit History 49 Commits
app		app
components		components
lib		lib
public		public
registry		registry
scripts		scripts
styles		styles
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.nvmrc		.nvmrc
CONTRIBUTING.md		CONTRIBUTING.md
CONTRIBUTORS.md		CONTRIBUTORS.md
INSTALLATION.md		INSTALLATION.md
LICENSE		LICENSE
README.md		README.md
REGISTRY.md		REGISTRY.md
components.json		components.json
next.config.mjs		next.config.mjs
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts
vitest.setup.ts		vitest.setup.ts

License

gfargo/feature-lock

Folders and files

Latest commit

History

Repository files navigation