ForgeWP

Adding Components to Your Theme

Install editable UI components with the ForgeWP CLI and understand what it changes in your project.

ForgeWP themes use ordinary React components. The registry gives you starter source code that the CLI places in your theme, where you can inspect and adapt it. It does not install a separate ForgeWP component runtime.

You do not need to know how component registries work to follow this guide. We will run one command, look at what it changes, and explain where the component code comes from.

Before you start

Open a terminal in the root of your ForgeWP theme. This is the folder containing package.json and wp.config.ts. The forgewp add command runs the shadcn CLI, so installing components generally requires network access.

ForgeWP also provides local versions of a few components. The CLI checks those after attempting the shadcn install and uses a local version when one is available.

Add a component

Pass one or more component names to the command:

Terminal
pnpm forgewp add card
pnpm forgewp add navbar hero-section

The names below have ForgeWP implementations in its local registry:

Table · 2 columns
Name
Component
404
Not-found page component
fade-reveal
Reveal animation component
hero-section
Hero section
navbar
Navigation bar
premium-gallery
Image gallery
pricing-table
Pricing table

For other names, the CLI uses the upstream shadcn registry. Which components are available there depends on shadcn's registry and the CLI version used during installation.

What the command does

Here is the installation flow. For a ForgeWP-local component, the CLI checks for an existing file before creating configuration or running shadcn. An existing file is preserved unless you explicitly pass --overwrite.

Flowchart
Rendering diagram...

In more detail, the CLI:

  1. Creates a default components.json in the theme root if the file is missing. This tells shadcn where component and CSS files live.
  2. Detects a package manager from its lockfile. It recognizes pnpm, Yarn, and Bun's bun.lockb; if none is found, it uses npm.
  3. Runs shadcn add <name> --yes.
  4. If ForgeWP has a local implementation, writes it to src/components/ui/<name>.tsx. If that target already existed, this step only runs when you passed --overwrite.
  5. Installs any missing Tailwind plugins declared by the local component and adds their @plugin directive to a recognized CSS entry file.
  6. When the selected style is forgewp, rewrites matching rounded utility names in the installed component files to rounded-none.
Can adding a component replace your edits?

A ForgeWP-local component is protected by default. If src/components/ui/<name>.tsx already exists, the command stops before creating configuration or running shadcn, and leaves the file unchanged. To deliberately replace it with the registry version, pass --overwrite; that discards the file's current contents, so review or commit your work first. This flag applies to ForgeWP-local overrides; upstream shadcn components follow the behavior of the shadcn CLI.

Find and edit the source

After installation, open the component under src/components/ui/. It is source code in your project, so you can change its markup, styles, and behavior like any other React component.

Theme files after adding a component
my-theme/
├── components.json
├── src/
│   ├── app/
│   │   └── globals.css
│   └── components/
│       └── ui/
│           └── card.tsx
└── wp.config.ts

Owning the source does not mean a component has no dependencies. A shadcn component may import packages such as Radix UI; shadcn handles dependencies for its registry components. ForgeWP can also install Tailwind plugins declared in local registry metadata.

Choose the corner style

The CLI reads the style value in wp.config.ts. You can override it for one command with --style=forgewp or --style=shadcn:

Terminal
pnpm forgewp add card --style=shadcn

With forgewp, a text transform changes matching rounded-* utility names in the installed component source to rounded-none. With shadcn, those utility names are left unchanged. This affects files being added, not every component already in your project.

Use the compiler package's config helper in wp.config.ts:

Add or change only the style property inside your existing configuration. Keep the other theme identity, settings, and feature entries.

wp.config.ts
1import { defineConfig } from "@forgewp/compiler/define-config"
2
3export default defineConfig({
4  // Keep your existing configuration here.
5  name: "My Theme",
6  slug: "my-theme",
7  // ADD OR UPDATE THIS PROPERTY.
8  style: "forgewp",
9})

Inspect the installed .tsx file to see exactly which classes were changed.

Options and troubleshooting

Component names can be positional arguments, and --name=<component> is also accepted. The supported style override is written as --style=<value>. Use --overwrite only when you intend to replace an existing ForgeWP-local component. ForgeWP passes --yes to the shadcn command internally.

Terminal
pnpm forgewp add navbar --overwrite

If installation fails, check that you are in the theme root, that the network can reach the shadcn registry, and that the requested local component exists in the ForgeWP UI package. A local component can still be installed if the shadcn step fails; a name with no local version requires shadcn to succeed.

Next, see Composing UI with WordPress Data for examples combining components with ForgeWP's post and menu primitives.