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.
categorized - Group integrations under their categories.
featured - Emphasize one integration beside the rest.
ecosystem - Show integrations surrounding a platform.
orbit - Arrange integrations around a central product node.
network - Connect integration cards in a network layout.
carousel - Scroll through a horizontal integration rail.
list - Present compact, full-width integration rows.
grouped - Separate integration groups with clear dividers.
split - Pair the directory with a featured connection.
logo-wall - Prioritize supplied logos over descriptions.
connected - Trace integrations along a vertical connector.
API
| Prop | Type | Description |
|---|---|---|
variant | IntegrationsVariant | Selects one of twelve compositions; defaults to grid. |
items | readonly IntegrationItem[] | Integration data with stable id and name. |
IntegrationItem.logo | ReactNode | Optional consumer-provided logo or mark. |
IntegrationItem.category | string | Optional category used for grouping and filtering. |
IntegrationItem.description | ReactNode | Optional integration summary. |
IntegrationItem.href | string | Optional link; the component preserves the supplied destination. |
IntegrationItem.featured | boolean | Marks an item for featured layouts. |
filterable | boolean | Adds a labeled search field and, when categories exist, a category select. Defaults to false. |
centerLabel | ReactNode | Optional center label for ecosystem and relationship layouts; defaults to Platform. |
| Shared section props | MarketingSectionBaseProps | Header, 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.
| Prop | Required | Default |
|---|---|---|
variant | No | "grid" |
items | Yes | — |
filterable | No | false |
centerLabel | No | "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.