Book a call

WritingBuilding a systemPart 4 of 4 in Components in depth

Component props best practices: designing APIs people can use

Props are a promise. They're the interface designers and engineers use every day, and once teams depend on one, changing it breaks their screens. The kinds of props, the rules we review them against, and how to keep Figma and code saying the same thing.

On this pageProps are a promise
  1. Props are a promise
  2. The eight kinds of props
  3. Five rules for good props
  4. How props work: down, then up
  5. Keep Figma and code in step
  6. A props review checklist
  7. The short version
  8. Frequently asked questions
  9. Further reading

The short answer

Component props are the API designers and engineers use every day, and a promise you'll have to keep for years. Good props: use one choice instead of several switches (variant="danger", not isPrimary isDanger); use the same names everywhere (variant, size, tone, disabled); make the default the right answer; never let props bypass the system with raw colours or pixel values; and only require what's essential. Keep the same properties, names and defaults in Figma and code.

  • Every prop you add is one you'll have to support. Add it only when it earns its place.
  • Information flows down through props; news flows up through events.
  • Name controlled and uncontrolled values the same way in every component.

Props are a promise

Think of a TV remote. A good one has a few clearly labelled buttons that do exactly what they say. Now imagine one where "volume up" only works if "mode B" is on, and pressing "mute" on input 2 changes the channel. That's what a component with badly designed props feels like.

Props matter for three reasons. They're the interface people use every day, so clarity saves time on every screen. They decide consistency: if a prop lets anyone pick any colour, they will, and the product drifts. And they're a promise: once teams use a prop, changing or removing it breaks their screens. That's a breaking change, with all the cost that implies.

The eight kinds of props

Almost every prop in every component library falls into one of eight kinds. Knowing them helps you spot what a component needs, and props that don't belong.

KindWhat it doesExample in codeIn Figma
VariantPicks one approved version from a fixed listvariant="primary"Variant property
SizePicks one approved sizesize="sm" | "md" | "lg"Variant property
SwitchTurns one thing on or offdisabled, loadingBoolean property
ContentText or information to showlabel="Email"Text property
SlotLets you put other components insideicon={<SendIcon />}, childrenInstance swap or slot
StateThe current value, and its starting valuevalue, defaultValue, openUsually a "state" variant
EventWhat to do when something happensonClick, onChangeNot represented (prototype only)
AccessibilityExtra information for assistive technologyaria-label="Close dialog"A note in the spec
Figma's component property types (variant, boolean, text, instance swap) line up neatly with most of these. When both sides use the same names and values, a designer's choices translate directly into code.

Five rules for good props

1. Prefer one choice over many switches

The most common mistake is using several on/off switches for what's really one choice. If a button has isPrimary, isDanger and isGhost, what happens when someone turns on two? Nobody knows. One variant prop with a list of allowed values makes impossible combinations impossible.

// ✕ Three switches, eight combinations, most of them meaningless
<Button isPrimary isDanger>Delete</Button>

// ✓ One choice, three valid options
<Button variant="danger">Delete</Button>

2. Use the same names everywhere

If buttons use variant, badges shouldn't use type and alerts shouldn't use kind. If buttons use size="sm", inputs shouldn't use size="small". Write down a short list of standard prop names and use it across the library. People then learn the library once, not component by component.

3. Make the default the right answer

The value a prop takes when nobody sets it should be the most common, safest choice. A button should default to medium and secondary, so the big primary button is a deliberate decision. A text field should default to a visible label, not a hidden one.

4. Don't let props bypass the system

Props like color="#FF3300" or padding={13} let anyone escape the foundations, and someone always will. Offer choices from the system (tone="critical", size="lg"), never raw values.

5. Only require what's essential

A component should work with as few props as possible. A button needs a label and something to do when pressed; everything else should have a sensible default. Every required prop is something someone will forget.

How props work: down, then up

In most modern frameworks, information flows down through props and news flows up through events. The screen tells the component what to show; when something happens inside it, the component tells the screen, which decides what to do.

Product screenKnows the data and the rules: tab = "invoices"
→
props downvalue="invoices"
→
Tabs componentKnows how to look and behave
→
event uponValueChange("payments")
Props flow down, events flow up. Given the same props, a component always looks the same, which is also what makes visual testing possible.

Controlled and uncontrolled

An uncontrolled component takes a defaultValue and looks after itself. A controlled component takes a value plus an event like onValueChange, and the screen stays in charge. Good libraries name these the same way in every component that has a value, so engineers learn the pattern once.

Passing things through

Components should pass along standard attributes they don't use themselves (an ID for testing, a data attribute, an extra ARIA attribute) to the underlying element. It means the system doesn't block teams from doing ordinary, legitimate things.

Keep Figma and code in step

Code propValuesDefaultFigma propertyWhat it's for
variantprimary · secondary · dangersecondaryVariant: VariantThe importance of the action. One primary per area.
sizesm · md · lgmdVariant: SizeMatch the density of the surrounding UI.
iconicon namenoneBoolean + instance swapAn optional icon before the label.
loadingtrue / falsefalseBoolean: LoadingShows progress and prevents double clicks.
disabledtrue / falsefalseVariant: State = DisabledCan't be used right now. Explain why nearby.
childrentext—Text: LabelThe label. Start with a verb: "Send invoice".
One button, documented as twins. Two small differences are agreed and written down: Figma splits the icon into a switch and a choice, and treats "disabled" as a visual state.

Put a table like this on every component's documentation page. See design system documentation for the full page template.

A props review checklist

  • Could two of these switches be one variant?
  • Does every name match the standard list used across the library?
  • Is the default the most common, safest choice?
  • Can any prop accept a raw colour, size or spacing value?
  • Is every required prop genuinely essential?
  • Are controlled and uncontrolled values named consistently?
  • Does the Figma component expose the same properties, names and defaults?
  • Are we sure we want to support this prop for years?

The short version

  • Props are an interface and a promise; add them sparingly.
  • One variant over many switches; the same names everywhere; good defaults.
  • Offer choices from the system, never raw values.
  • Props down, events up; consistent controlled and uncontrolled patterns.
  • Keep Figma properties and code props as twins, and document both.

Frequently asked questions

Should a component accept a className or style prop?

Usually yes for layout (positioning, width), as an escape hatch passed to the root element. Don't use it as the way to change colours or spacing; offer system choices for those.

How do I rename a prop safely?

Add the new name in a minor release alongside the old one, deprecate the old with a warning and a codemod, then remove it in the next major.

variant, kind, type or appearance?

The specific word matters less than using one everywhere. variant is the most common and maps well to Figma's variant properties.

Should slots or props be preferred?

Props for constrained choices; slots where teams need to compose content, such as a card's body. Slots give flexibility; props give consistency.

Further reading