Custom components

When the built-in set runs out, build your own in Component Studio. A custom component becomes a tag available in every guide and endpoint description in the project. Custom components need the Growth plan or higher.

Building one

Define props

Each prop has a name and a default value. The default is used whenever an author omits the prop.
Compose the layout

Build it visually, or write the template directly. Templates are MDX, so they can nest built-in and other custom components.
Style it

Scoped CSS, applied under the component's own class so it can't leak into the rest of the page.

Props and children

Props are substituted into the template with {{propName}}. Children go where you put {{children}}.

<div class="pricing-tier">
  <h3>{{name}}</h3>
  <p class="price">{{price}}</p>
  {{children}}
</div>

An author then writes:

<PricingTier name="Growth" price="$79/mo">
  Everything in Starter, plus versioning.
</PricingTier>

Props arrive lowercased

The renderer parses component tags as HTML, which lowercases attribute names. A prop declared ctaHref arrives as ctahref. Octri resolves declared props case-insensitively, so ctaHref in your template still matches, but it's worth knowing when something doesn't bind.

Naming

A custom component can't shadow a built-in

Names that collide with a built-in tag are rejected. If you want a different Callout, build NoticeBox, not Callout.

Custom component names are PascalCase and unique per project.

Scoped CSS

Your CSS is scoped to the component's own wrapper class, so a selector like .price { color: red } only applies inside that component. The stylesheet is emitted once per page, and only when the component is actually used.

Where they work

A custom component renders anywhere the built-ins do: the public docs, the studio editor, and the live preview. Nesting works, and there's a depth limit to stop a template that references itself from taking the page down.

Prefer a built-in when one fits

A custom component is code you maintain. <Card> with an icon covers most of what people build custom components for, and it already handles dark mode, mobile, and hover states.

Writing one as code

A component built in the visual builder is also readable as JSX: the Files panel shows it as components/<Name>.jsx, with its stylesheet beside it. It's a restricted JSX, holding only what the builder can represent. Anything else is an error that names the problem, rather than something quietly dropped when you save.

<div class="pricing-tier">
  <h3>{name}</h3>
  <a href={url}>Choose {name}</a>
  {children}
</div>

You write	What it means
`<div class="x">`	An element. Attribute values are quoted strings
`href={url}`	An attribute bound to the prop `url`
`width={2}`, `open`, `open={false}`	Number and boolean attribute values
`Hello {name}`	Text containing a prop
`{children}`	Where an author's content goes
`{"{"}`	Literal text, for writing `{`, `}`, `<`, `>` and line breaks

Some things are refused, to keep your docs safe:

Refused	Instead
Event handlers such as `onClick`	Use custom code for behavior
An inline `style` attribute	Use the component's stylesheet
More than one root element	Wrap them in one

Managing components

Where	What you can do
Docs settings, under Components	Create, edit and delete them
octri.json	Edit a component's description and props
The CLI	List, show, push from a file and remove

Changes to a component apply when you save, not when you publish. A page using one changes as soon as you do, so be careful with components used widely.

Components

Check the built-ins first.

Writing guides

Where components get used.