Skip to Content

CareersSection

Present job openings by role, department, location, employment type, benefits, culture, and application link.

CareersSection displays application-owned job data and benefits. It can group opportunities by department or location and provides an empty state when no openings are supplied.

Beta API maturity: Beta.

Installation

import {
  CareersSection,
  type BusinessCareerPosition,
  type CareersSectionVariant,
} from "@puzzle-ui/pieces";

Variant previews

Each of the twelve variants has its own preview, using fictional consultancy roles across product, brand, and research teams.

list - Present open roles in a straightforward list.

390 × 844

grid - Browse openings as responsive cards.

390 × 844

featured - Highlight a priority role.

390 × 844

departments - Group openings by department.

390 × 844

culture - Pair company culture with open roles.

390 × 844

split - Balance roles and benefits in two columns.

390 × 844

benefits - Give the employee benefits more emphasis.

390 × 844

editorial - Add room for a considered culture statement.

390 × 844

cards - Separate each opportunity on a card surface.

390 × 844

locations - Group openings by workplace or region.

390 × 844

compact - Keep a dense role list concise.

390 × 844

hiring - Make active hiring priorities easy to spot.

390 × 844

API

PropTypeDescription
variantCareersSectionVariantlist (default), grid, featured, departments, culture, split, benefits, editorial, cards, locations, compact, or hiring.
positionsreadonly BusinessCareerPosition[]Openings with unique ID and title; optional department, location, employment type, description, application link, and featured state.
benefitsreadonly BusinessBenefit[]Optional benefit items with unique IDs and titles.
cultureReactNodeOptional company culture content.
emptyStateReactNodeOptional replacement for the default no-openings message.
featuredPositionBusinessCareerPosition | stringOptional position object or ID promoted in the featured layouts.
Shared section propsMarketingSectionBasePropsHeading, actions, root element, native section attributes, and children.

Required and default values

Requiredness follows the exported TypeScript type. A dash means no component-level default is applied; variant-specific requirements are described in the API table above.

PropRequiredDefault
variantNo"list"
positionsYes—
benefitsNoempty array
cultureNo—
emptyStateNo"There are no open positions right now."
featuredPositionNo—

Usage

<CareersSection
  variant="departments"
  title="Work with us"
  positions={[
    {
      id: "designer",
      title: "Senior product designer",
      department: "Product",
      location: "Amsterdam",
      employmentType: "Full-time",
      description: "Shape tools for growing teams.",
      href: "/careers/product-designer",
    },
  ]}
  benefits={[
    { id: "learning", title: "Learning budget" },
    { id: "flexibility", title: "Flexible work" },
  ]}
/>

Accessibility and rendering

Position titles and application links are semantic headings and native anchors. Department and location groupings retain their heading structure. The default empty state remains visible when positions is empty, including grouped layouts. Keep IDs unique and stable; the component validates supplied positions and benefits. There is no application workflow or backend, and rendering is server compatible.

Customization

Use the component's className and documented slots to adapt the composition. Prefer a caller-provided ReactNode for media, actions, or controls rather than adding domain behavior to the section.

import type { ComponentProps } from "react";
import { CareersSection } from "@puzzle-ui/pieces";

type CareersSectionProps = ComponentProps<typeof CareersSection>;

export function CustomizedSection(props: CareersSectionProps) {
  return <CareersSection {...props} className={[props.className, "brand-section"].filter(Boolean).join(" ")} />;
}

Responsive behavior

Use the preview device selector to review mobile, tablet, and desktop widths. The built-in variant controls section structure; ensure application-provided media, form controls, and children can shrink or wrap without horizontal overflow. Use the existing responsive breakpoints in scoped CSS when the consuming layout needs a product-specific adjustment.

Theme support

The section consumes semantic variables from @puzzle-ui/theme and inherits active or scoped themes. Wrap the application with Theme, and use semantic roles such as text, surface, border, and primary for local overrides. Avoid hard-coded colors, spacing, radii, and shadows.

.brand-section {
  color: var(--puzzle-color-text);
  background: var(--puzzle-color-surface);
  border-color: var(--puzzle-color-border);
}

Composition

Compose this section with the UI primitives named in its API and use the documented slots for consumer-owned controls or media. Keep data fetching, routing, validation, permissions, and persistence in the application. The children slot is intended for additional content that belongs with this section, not as a substitute for its typed data model.

TypeScript example

The package exports this component from its root. Derive a wrapper's exact prop type from the public component rather than widening it:

import type { ComponentProps } from "react";
import { CareersSection } from "@puzzle-ui/pieces";

type CareersSectionProps = ComponentProps<typeof CareersSection>;

export function SectionWrapper(props: CareersSectionProps) {
  return <CareersSection {...props} />;
}

Framework compatibility

The section is router-independent. Static compositions can be server-rendered; place callback-driven interactions in the framework's client boundary. See Next.js and TanStack Start integration for runnable framework examples and SSR guidance.