Lens Quick Widgets UI Library

A comprehensive React component library for building applications with Lens Protocol. This package provides ready-to-use UI components to streamline your development process.

Table of Contents

• Installation
• Provider Setup
• Components
  • SignInWithLens
  • Post
  • PostsList
  • Account
  • AccountsList
• Theming
• Types
• Advanced Usage
• Accessing Lens Protocol React API
• Contributing

Installation

# Install the package along with required dependencies
npm install lens-quick-widgets wagmi connectkit

# Or using yarn
yarn add lens-quick-widgets wagmi connectkit

Note: lens-quick-widgets requires both wagmi and connectkit as peer dependencies for wallet connection and authentication.

Provider Setup

The library requires a provider component to handle authentication, theming, and Lens Protocol integration. Wrap your application with LensWidgetProvider:

import { LensWidgetProvider, Theme } from "lens-quick-widgets"
import { createConfig, http, WagmiProvider } from "wagmi"
import { lens } from "wagmi/chains"
import { getDefaultConfig } from "connectkit"

// Configure Wagmi (required for wallet connections)
const config = createConfig(
  getDefaultConfig({
    chains: [lens],
    transports: {
      [lens.id]: http(
        `https://eth-mainnet.g.alchemy.com/v2/${YOUR_ALCHEMY_ID}`
      ),
    },
    walletConnectProjectId: YOUR_WALLET_CONNECT_PROJECT_ID,
    appName: "Your App Name",
  })
)

// In your app root component
const App = () => {
  return (
    <WagmiProvider config={config}>
      <LensWidgetProvider
        defaultTheme={Theme.light}
        isTestnet={false}
        appAddress="0xYourAppAddressIfYouHaveOne"
      >
        {/* Your application components */}
      </LensWidgetProvider>
    </WagmiProvider>
  )
}

Provider Props

| Prop | Type | Default | Description | | ------------ | ----------- | ----------------------- | ------------------------------------ | | defaultTheme | Theme | Theme.default | Default theme for all components | | isTestnet | boolean | false | Whether to use Lens Protocol testnet | | appAddress | string | Lens Widget app address | Your app's blockchain address | | children | ReactNode | - | Child components |

Components

SignInWithLens

A button that handles the entire Lens authentication flow, from wallet connection to profile authentication.

import { SignInWithLens, Theme } from "lens-quick-widgets"
;<SignInWithLens
  theme={Theme.dark}
  onConnectWallet={(address) => console.log(`Connected: ${address}`)}
  onLogin={(account) => console.log("Logged in:", account)}
  onLogout={() => console.log("User logged out")}
/>

Props

| Prop | Type | Default | Description | | --------------- | --------------------------- | ------------- | --------------------------- | | theme | Theme | Context theme | Visual theme of the button | | onConnectWallet | (address: string) => void | - | Called when wallet connects | | onLogin | (account: any) => void | - | Called on successful login | | onLogout | () => void | - | Called on logout |

Post

Displays a single Lens Protocol post with rich formatting, media support, and interactive features.

import { Post, Theme } from "lens-quick-widgets"
;<Post
  postId="0x01-0x01"
  theme={Theme.light}
  hideInteractions={false}
  showStats={true}
  showFollow={true}
  contentPreviewLimit={400}
  visibleStats={["upvotes", "comments", "reposts"]}
  visibleButtons={["like", "repost", "comment"]}
  onLike={(post) => console.log("Post liked:", post.id)}
  onRepost={(post) => console.log("Post reposted:", post.id)}
  onComment={(post) => console.log("Comment on post:", post.id)}
  onClick={(post) => console.log("Post clicked:", post.id)}
/>

Props

| Prop | Type | Default | Description | | ------------------- | ------------------------------------------------------------------------------------------------ | ------------- | ------------------------------------------ | | post | AnyPost | - | Direct post object (alternative to postId) | | postId | string | - | ID of the post to fetch | | theme | Theme | Context theme | Visual theme | | containerStyle | React.CSSProperties | - | Custom container styling | | hideInteractions | boolean | false | Hide interaction buttons | | showStats | boolean | true | Show post statistics | | showFollow | boolean | true | Show follow button for post author | | showUnfollowButton | boolean | false | Show unfollow button for followed users | | showHeyButton | boolean | false | Show button to open post on Hey.xyz | | contentPreviewLimit | number | 400 | Character limit before "Show more" | | visibleStats | Array<"upvotes" \| "comments" \| "reposts" \| "quotes" \| "bookmarks" \| "collects" \| "tips"> | All stats | Which stats to display | | visibleButtons | Array<"like" \| "repost" \| "comment"> | All buttons | Which interaction buttons to show | | onLike | (post: AnyPost) => void | - | Called when post is liked | | onRepost | (post: AnyPost) => void | - | Called when post is reposted | | onComment | (post: AnyPost) => void | - | Called when comment button clicked | | onClick | (post: AnyPost) => void | - | Called when post is clicked | | onLoad | (post: AnyPost) => void | - | Called when post data loads |

PostsList

Displays a customizable feed of Lens Protocol posts with infinite scrolling and filtering options.

import { PostsList, PageSize, Theme } from "lens-quick-widgets"
;<PostsList
  theme={Theme.green}
  pageSize={PageSize.Ten}
  searchQuery="blockchain"
  postsOf="stani"
  widthOfPostCard="100%"
  hideInteractions={false}
  showStats={true}
  showHeyButton={true}
  contentPreviewLimit={200}
  onPostClick={(post) => console.log("Post clicked:", post.id)}
  onLike={(post) => console.log("Post liked:", post.id)}
  onRepost={(post) => console.log("Post reposted:", post.id)}
/>

Props

| Prop | Type | Default | Description | | ------------------- | ------------------------------------------------------------------------------------------------ | -------------- | --------------------------------------- | | accountScore | { atLeast: number } | { lessThan: number } | - | Filter by account score | | apps | EvmAddress[] | - | Filter by apps used to create posts | | authors | EvmAddress[] | - | Filter by post authors | | metadata | Object | - | Filter by post metadata | | posts | PostId[] | - | Filter to specific post IDs | | postTypes | LensPostType[] | - | Filter by post types | | searchQuery | string | - | Search for posts with specific content | | postsOf | string | - | Show posts from a specific Lens user | | pageSize | PageSize | PageSize.Ten | Number of posts per page | | theme | Theme | Context theme | Visual theme | | widthOfPostCard | string \| number | '100%' | Width of each post card | | containerStyle | React.CSSProperties | - | Custom container styling | | postStyle | React.CSSProperties | - | Custom post styling | | postContainerStyle | React.CSSProperties | - | Custom post container styling | | hideInteractions | boolean | false | Hide interaction buttons | | showStats | boolean | true | Show post statistics | | showFollow | boolean | true | Show follow button for post authors | | showUnfollowButton | boolean | false | Show unfollow button for followed users | | contentPreviewLimit | number | 400 | Character limit before "Show more" | | visibleStats | Array<"upvotes" \| "comments" \| "reposts" \| "quotes" \| "bookmarks" \| "collects" \| "tips"> | All stats | Which stats to display | | visibleButtons | Array<"like" \| "repost" \| "comment"> | All buttons | Which interaction buttons to show | | onPostClick | (post: AnyPost) => void | - | Called when a post is clicked | | onLike | (post: AnyPost) => void | - | Called when a post is liked | | onRepost | (post: AnyPost) => void | - | Called when a post is reposted |

Account

Displays a Lens Protocol user profile with customizable styling and size options.

import { Account, Theme, Size } from "lens-quick-widgets"
;<Account
  localName="stani"
  theme={Theme.mint}
  size={Size.medium}
  hideFollowButton={false}
  showUnfollowButton={false}
  showHeyButton={true}
  fontSize="16px"
  onAccountLoad={(account) => console.log("Account loaded:", account)}
  onClick={(account, stats) => console.log("Account clicked:", account, stats)}
  onFollowed={() => console.log("Account followed/unfollowed")}
/>

Props

| Prop | Type | Default | Description | | -------------------------- | -------------------------------------------- | ------------- | --------------------------------------------------------------- | | account | AccountType | - | Direct account object (alternative to localName/accountAddress) | | accountAddress | string | - | Blockchain address of the account to display | | localName | string | - | Lens handle of the account to display | | theme | Theme | Context theme | Visual theme | | size | Size | Size.medium | Size variant of the component | | containerStyle | React.CSSProperties | - | Custom container styling | | followButtonStyle | React.CSSProperties | - | Custom follow button styling | | followButtonContainerStyle | React.CSSProperties | - | Custom follow button container styling | | followButtonTextColor | string | - | Custom follow button text color | | hideFollowButton | boolean | false | Hide the follow button | | showUnfollowButton | boolean | false | Show unfollow button for followed users | | showHeyButton | boolean | false | Show button to open profile on Hey.xyz | | fontSize | string | Based on size | Custom font size | | onAccountLoad | (account: AccountType) => void | - | Called when account data loads | | onError | (error: Error) => void | - | Called on error | | onClick | (account: AccountType, stats: any) => void | - | Called when component is clicked | | onFollowed | () => void | - | Called when account is followed/unfollowed |

AccountsList

Displays a customizable list of Lens Protocol accounts with filtering and infinite scrolling.

import {
  AccountsList,
  PageSize,
  Size,
  Theme,
  AccountsOrderBy,
} from "lens-quick-widgets"
;<AccountsList
  theme={Theme.peach}
  accountSize={Size.small}
  pageSize={PageSize.Ten}
  searchBy="lens"
  followersOf="stani"
  orderBy={AccountsOrderBy.AccountScore}
  hideFollowButton={false}
  showUnfollowButton={false}
  onAccountClick={(account) => console.log("Account clicked:", account)}
  onFollowed={() => console.log("Account followed/unfollowed")}
/>

Props

| Prop | Type | Default | Description | | -------------------------- | --------------------- | ------------------------------- | ------------------------------------------- | | searchBy | string | - | Search accounts by name or handle | | addresses | string[] | - | Show accounts with specific addresses | | ownedBy | string[] | - | Show accounts owned by specific addresses | | localNames | string[] | - | Show accounts with specific handles | | managedBy | string | - | Show accounts managed by a specific address | | followersOf | string | - | Show followers of a specific handle | | followingsOf | string | - | Show accounts followed by a specific handle | | pageSize | PageSize | PageSize.Ten | Number of accounts per page | | theme | Theme | Context theme | Visual theme | | accountSize | Size | Size.small | Size of account components | | orderBy | AccountsOrderBy | AccountsOrderBy.BestMatch | Sorting for regular accounts | | followersOrderBy | FollowersOrderBy | FollowersOrderBy.AccountScore | Sorting for followers | | followingOrderBy | FollowingOrderBy | FollowingOrderBy.AccountScore | Sorting for followings | | containerStyle | React.CSSProperties | - | Custom container styling | | accountStyle | React.CSSProperties | - | Custom account component styling | | followButtonStyle | React.CSSProperties | - | Custom follow button styling | | followButtonContainerStyle | React.CSSProperties | - | Custom follow button container styling | | followButtonTextColor | string | - | Custom follow button text color | | hideFollowButton | boolean | false | Hide the follow button | | showUnfollowButton | boolean | false | Show unfollow button for followed users | | fontSize | string | - | Custom font size |

Theming

The library provides several built-in themes:

import { Theme } from "lens-quick-widgets"

// Available themes
Theme.default // Default Lens theme
Theme.light // Light theme
Theme.dark // Dark theme
Theme.green // Green theme
Theme.blonde // Blonde theme
Theme.lavender // Lavender theme
Theme.mint // Mint theme
Theme.peach // Peach theme

Types

Common types used in the library:

// Component sizes
enum Size {
  compact = "compact", // Minimal inline version
  small = "small", // Small version
  medium = "medium", // Standard size
  large = "large", // Full featured size
}

// Page size for lists
enum PageSize {
  Ten = 10,
  Fifty = 50,
}

// Account sorting options
enum AccountsOrderBy {
  BestMatch = "BEST_MATCH",
  AccountScore = "ACCOUNT_SCORE",
  Alphabetical = "ALPHABETICAL",
}

// Followers sorting options
enum FollowersOrderBy {
  AccountScore = "ACCOUNT_SCORE",
  Asc = "ASC",
  Desc = "DESC",
}

// Following sorting options
enum FollowingOrderBy {
  AccountScore = "ACCOUNT_SCORE",
  Asc = "ASC",
  Desc = "DESC",
}

Advanced Usage

Custom Styling

All components accept style customization props. For example:

<Post
  postId="0x01-0x01"
  containerStyle={{
    boxShadow: "0 4px 12px rgba(0, 0, 0, 0.1)",
    borderRadius: "12px",
    maxWidth: "600px",
  }}
/>

Authentication Flow

The authentication flow with SignInWithLens has three stages:

1. Wallet Connection - User connects their blockchain wallet
2. Challenge Signing - User signs a message to prove ownership
3. Authentication - User is authenticated with Lens Protocol

You can track this flow with the provided callbacks:

<SignInWithLens
  onConnectWallet={(address) => console.log(`Wallet connected: ${address}`)}
  onLogin={(account) => {
    console.log("Authenticated account:", account)
    // Save user session, redirect, etc.
  }}
  onLogout={() => {
    console.log("User logged out")
    // Clear session, redirect, etc.
  }}
/>

Advanced Filtering for PostsList

<PostsList
  // Filter by content type
  metadata={{
    mainContentFocus: ["IMAGE", "VIDEO"],
    contentWarning: { oneOf: ["NSFW", "SENSITIVE"] },
    tags: { oneOf: ["blockchain", "crypto"] },
  }}
  // Filter by author reputation
  accountScore={{ atLeast: 50 }}
  // Filter by post type
  postTypes={["POST", "COMMENT"]}
/>

Accessing Lens Protocol React API

This library re-exports the complete @lens-protocol/react library as LensProtocolReact and the client actions as LensProtocolActions, allowing you to access any hooks, functions, or types from the original libraries:

import { LensProtocolReact, LensProtocolActions } from "lens-quick-widgets"
import { useState, useEffect } from "react"

function CustomAccountStatsFetcher({ localName }) {
  // Access hooks from the Lens Protocol library
  const { currentSession } = LensProtocolReact.usePublicClient()

  // Example state for storing fetched data
  const [accountStats, setAccountStats] = useState(null)
  const [loading, setLoading] = useState(false)

  // Custom function to fetch account stats using Lens Protocol Actions
  const fetchStats = async () => {
    if (!currentSession || !localName) return

    setLoading(true)
    try {
      // Use LensProtocolActions instead of importing from @lens-protocol/client/actions
      const result = await LensProtocolActions.fetchAccountStats(
        currentSession,
        {
          username: {
            localName: localName,
          },
        }
      )

      if (result?.isOk()) {
        setAccountStats(result.value)
        console.log("Account stats:", result.value)
      } else if (result?.isErr()) {
        console.error("Error fetching account stats:", result.error)
      }
    } catch (err) {
      console.error("Unexpected error:", err)
    } finally {
      setLoading(false)
    }
  }

  // Fetch stats when component mounts and dependencies change
  useEffect(() => {
    fetchStats()
  }, [currentSession, localName])

  return (
    <div>
      <button onClick={fetchStats} disabled={loading}>
        {loading ? "Loading..." : "Refresh Stats"}
      </button>

      {accountStats && (
        <div>
          <h3>Account Stats for {localName}:</h3>
          <p>Total Posts: {accountStats.posts}</p>
          <p>Comments: {accountStats.comments}</p>
          <p>Mirrors: {accountStats.mirrors}</p>
          <p>Followers: {accountStats.followers}</p>
          <p>Following: {accountStats.following}</p>
        </div>
      )}
    </div>
  )
}

This approach gives you the flexibility to directly use any functionality from the Lens Protocol libraries while still taking advantage of our pre-built UI components. The LensProtocolActions export provides access to all client actions from @lens-protocol/client/actions, making it easy to perform operations like fetching account stats, creating posts, and more.

For complete documentation on available hooks and functions, refer to the official Lens Protocol React documentation.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This package is licensed under the MIT License. For complete documentation on available hooks and functions, refer to the official Lens Protocol React documentation.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This package is licensed under the MIT License.