Using components

All components are named exports from @falcon/ui-kit:

import { Button, Card, CardHeader, CardTitle } from "@falcon/ui-kit";

Styles

Import Falcon CSS once at the app entrypoint:

import "@falcon/ui-kit/dist/index.css";

Compound components

Many components are composed of named sub-components that share a prefix with the parent: Card + CardHeader, Sidebar + SidebarMenu + SidebarMenuItem, and so on. Assemble them in JSX rather than passing configuration objects:

<Card>
  <CardHeader>
    <CardTitle>Order #1042</CardTitle>
  </CardHeader>
</Card>

Use sub-components with their matching component family. Some families provide context and will throw outside their provider; others rely on shared styling and semantics. Do not mix sub-components across families.

Composing rendered elements

Some trigger and link sub-components use render to apply Falcon behavior to a caller-provided element without adding an extra wrapper. Pass the element shell to render, then put the visible label as children:

<DialogTrigger render={<Button variant="outline" />}>
  Edit account
</DialogTrigger>

Use this pattern for components that document render. Components that use a different composition prop document that exception on their own page.

Variants and sizes

Use variant and size props for the built-in appearances:

<Button variant="outline" size="sm">
  Cancel
</Button>

Overriding styles

Pass className to layer additional Tailwind utilities on top of a component’s defaults. Prefix every utility with tw::

<Button className="tw:w-full">Submit</Button>

Classes without the tw: prefix are not Tailwind and will not apply.

Icons

Import icon components directly from @falcon/ui-kit. Every icon has an Icon suffix. Never inline raw SVGs.

import { CircleCheckIcon } from "@falcon/ui-kit";

<CircleCheckIcon size={16} />;

See Icons for icon naming, sizing, and custom Falcon icons.

Legacy components

Legacy components are in a separate entrypoint and must be imported from @falcon/ui-kit/dist/legacy, not from @falcon/ui-kit:

import { Button, Typography, FlexWrapper } from "@falcon/ui-kit/dist/legacy";

Do not mix imports between the two entrypoints; legacy and modern components are independent and do not share context or tokens. Any component used inside a legacy example must come from the legacy entrypoint unless it is plain React or HTML.