Skip to main content
The search command (also available as list) searches for items across one or more registries. Use it to discover available components, themes, and other registry items.

​
Usage

shadcn search <registries...>

shadcn list <registries...>

​
Arguments

​
registries
string[]
required
The registry names or URLs to search. Registry names must be prefixed with @.

​
Options

​
--cwd
string
The working directory. Defaults to the current directory.
​
--query
string
Query string to filter results.
​
--limit
number
default:"100"
Maximum number of items to display per registry.
​
--offset
number
default:"0"
Number of items to skip.

​
Examples

​
Search the default shadcn registry

shadcn search @shadcn

​
Search with a query

shadcn search @shadcn --query button
Output: 
[
  {
    "name": "button",
    "type": "registry:ui",
    "description": "Displays a button or a component that looks like a button.",
    "registry": "@shadcn"
  }
]

​
Search multiple registries

shadcn search @shadcn @custom-registry

​
Limit results

shadcn search @shadcn --limit 10

​
Paginate results

shadcn search @shadcn --offset 20 --limit 10

​
Search by URL

shadcn search https://ui.shadcn.com/r

​
What it does

  1. Reads your components.json (if it exists) or uses default configuration
  2. Resolves registry URLs
  3. Fetches the registry index
  4. Filters results by query (if provided)
  5. Applies limit and offset
  6. Outputs results as JSON

​
Output structure

Each search result includes:
  • name - Item name
  • type - Registry type
  • description - Item description (if available)
  • registry - Registry identifier
  • meta - Additional metadata (if available)

​
Registry types

Search results can include:
  • registry:ui - UI components
  • registry:block - UI blocks and sections
  • registry:hook - React hooks
  • registry:lib - Library utilities
  • registry:theme - Themes
  • registry:style - Style systems
  • registry:base - Base configurations
  • registry:example - Example implementations

​
Working with custom registries

To search a custom registry, add it to your components.json: 
{
  "registries": {
    "@my-registry": {
      "url": "https://my-registry.com/r"
    }
  }
}
Then search it: 
shadcn search @my-registry
Or search directly by URL without configuration: 
shadcn search https://my-registry.com/r

​
Use cases

​
Browse available components

shadcn search @shadcn | jq -r '.[].name' | sort

​
Find form-related components

shadcn search @shadcn --query form

​
Count available items

shadcn search @shadcn | jq 'length'

​
Filter by type

shadcn search @shadcn | jq '.[] | select(.type == "registry:ui")'

​
Get component descriptions

shadcn search @shadcn | jq '.[] | {name, description}'

​
Working with output

The JSON output can be processed with jq: 
# Get component names only
shadcn search @shadcn | jq -r '.[].name'

# Filter UI components
shadcn search @shadcn | jq '.[] | select(.type == "registry:ui")'

# Pretty print
shadcn search @shadcn | jq '.'

# Save to file
shadcn search @shadcn > components.json

​
Notes

  • Registry names must be prefixed with @
  • Supports partial components.json files
  • Works without a components.json file (uses defaults)
  • Automatically configures registries if needed
  • Search queries are case-insensitive
  • Results are always returned as JSON

Build docs developers (and LLMs) love

Get started for freeTalk to us