Skip to Content

IntegrationsSection

Organize SaaS integrations by category, highlight key connections, and optionally filter the directory.

IntegrationsSection displays integration names, consumer-supplied logos, descriptions, categories, and links. Its variants include categorized directories, featured integrations, relationship diagrams, and a horizontal carousel.

Beta API maturity: Beta.

Installation

import {
  IntegrationsSection,
  type IntegrationItem,
} from "@puzzle-ui/pieces";

Variant previews

Each variant has a standalone preview. The examples use fictional SaaS integrations and enable the search and category filters.

grid - Browse a balanced directory of integrations.

390 × 844

categorized - Group integrations under their categories.

390 × 844

featured - Emphasize one integration beside the rest.

390 × 844

ecosystem - Show integrations surrounding a platform.

390 × 844

orbit - Arrange integrations around a central product node.

390 × 844

network - Connect integration cards in a network layout.

390 × 844

carousel - Scroll through a horizontal integration rail.

390 × 844

list - Present compact, full-width integration rows.

390 × 844

grouped - Separate integration groups with clear dividers.

390 × 844

split - Pair the directory with a featured connection.

390 × 844

logo-wall - Prioritize supplied logos over descriptions.

390 × 844

connected - Trace integrations along a vertical connector.

390 × 844

API

PropTypeDescription
variantIntegrationsVariantSelects one of twelve compositions; defaults to grid.
itemsreadonly IntegrationItem[]Integration data with stable id and name.
IntegrationItem.logoReactNodeOptional consumer-provided logo or mark.
IntegrationItem.categorystringOptional category used for grouping and filtering.
IntegrationItem.descriptionReactNodeOptional integration summary.
IntegrationItem.hrefstringOptional link; the component preserves the supplied destination.
IntegrationItem.featuredbooleanMarks an item for featured layouts.
filterablebooleanAdds a labeled search field and, when categories exist, a category select. Defaults to false.
centerLabelReactNodeOptional center label for ecosystem and relationship layouts; defaults to Platform.
Shared section propsMarketingSectionBasePropsHeader, section element, theme, native 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"grid"
itemsYes—
filterableNofalse
centerLabelNo"Platform"

Usage

const integrations: IntegrationItem[] = [
  {
    id: "relay",
    name: "Relay Email",
    logo: <img src="/logos/relay.svg" alt="" />,
    category: "Messaging",
    description: "Send project updates to the right channel.",
    href: "https://example.com/relay",
  },
  {
    id: "beacon",
    name: "Beacon Analytics",
    category: "Analytics",
    description: "Include product events in workspace reports.",
  },
];

<IntegrationsSection
  variant="categorized"
  title="Connect your stack"
  items={integrations}
  filterable
/>;

Filtering searches the integration name, category, and plain-text descriptions. An empty result announces that no integrations match. If description contains rich React content, only the name and category are searchable.

Accessibility

Search and category controls have visible labels and use native inputs. Linked integrations are native anchors; logo alternatives remain the consumer's responsibility. The carousel is a keyboard-focusable horizontal scroller and does not auto-advance.

All integration content is provided by the caller. The component is server-renderable and does not make network requests or infer integration availability.

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 { IntegrationsSection } from "@puzzle-ui/pieces";

type IntegrationsSectionProps = ComponentProps<typeof IntegrationsSection>;

export function CustomizedSection(props: IntegrationsSectionProps) {
  return <IntegrationsSection {...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 { IntegrationsSection } from "@puzzle-ui/pieces";

type IntegrationsSectionProps = ComponentProps<typeof IntegrationsSection>;

export function SectionWrapper(props: IntegrationsSectionProps) {
  return <IntegrationsSection {...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.