or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

ai-advanced.md data-display.md form-components.md index.md input-selection.md loading-progress.md theming-customization.md tiles-layout.md

tile.json

Layout & Navigation

Flexible layout system with CSS Grid, navigation components, and application shell elements for building complete responsive interfaces.

Capabilities

Grid Layout System

Responsive grid system based on CSS Grid with breakpoint support and flexible column layouts.

/**
 * Grid container component
 */
interface GridProps {
  /** Element type to render */
  as?: React.ElementType;
  /** Condensed spacing */
  condensed?: boolean;
  /** Narrow margins */
  narrow?: boolean;
  /** Full width grid */
  fullWidth?: boolean;
  /** Grid children */
  children: React.ReactNode;
  /** CSS class name */
  className?: string;
}

/**
 * Grid row component
 */
interface RowProps {
  /** Element type to render */
  as?: React.ElementType;
  /** Condensed spacing */
  condensed?: boolean;
  /** Narrow margins */
  narrow?: boolean;
  /** Row children */
  children: React.ReactNode;
  /** CSS class name */
  className?: string;
}

/**
 * Grid column component with responsive breakpoints
 */
interface ColumnBaseProps {
  /** Element type to render */
  as?: React.ElementType;
  /** Column children */
  children: React.ReactNode;
  /** CSS class name */
  className?: string;
  /** Small breakpoint (up to 671px) - column span or object with span/offset */
  sm?: number | { span?: number; offset?: number };
  /** Medium breakpoint (672px - 1055px) - column span or object with span/offset */
  md?: number | { span?: number; offset?: number };
  /** Large breakpoint (1056px - 1311px) - column span or object with span/offset */
  lg?: number | { span?: number; offset?: number };
  /** Extra large breakpoint (1312px - 1583px) - column span or object with span/offset */
  xlg?: number | { span?: number; offset?: number };
  /** Max breakpoint (1584px+) - column span or object with span/offset */
  max?: number | { span?: number; offset?: number };
}

/**
 * Column hang component for breaking out of grid
 */
interface ColumnHangProps extends ColumnBaseProps {
  /** Left hang */
  left?: boolean;
  /** Right hang */
  right?: boolean;
}

Usage Examples:

import { Grid, Row, Column } from "@carbon/react";

// Basic grid layout
<Grid>
  <Row>
    <Column sm={4} md={8} lg={16}>
      <h1>Main Content</h1>
    </Column>
  </Row>
  <Row>
    <Column sm={4} md={4} lg={8}>
      <p>Left content</p>
    </Column>
    <Column sm={4} md={4} lg={8}>
      <p>Right content</p>
    </Column>
  </Row>
</Grid>

// Responsive grid with offsets
<Grid>
  <Row>
    <Column 
      sm={{ span: 4 }}
      md={{ span: 6, offset: 1 }}
      lg={{ span: 8, offset: 4 }}
    >
      <h2>Centered Content</h2>
    </Column>
  </Row>
</Grid>

// Condensed grid
<Grid condensed>
  <Row>
    <Column lg={4}>Card 1</Column>
    <Column lg={4}>Card 2</Column>
    <Column lg={4}>Card 3</Column>
    <Column lg={4}>Card 4</Column>
  </Row>
</Grid>

Stack Layout

Simple vertical layout component with consistent spacing between elements.

/**
 * Stack layout component for vertical spacing
 */
interface StackProps {
  /** Stack children */
  children: React.ReactNode;
  /** Gap between items (1-12) */
  gap?: number;
  /** Element type to render */
  as?: React.ElementType;
  /** Orientation */
  orientation?: "horizontal" | "vertical";
  /** CSS class name */
  className?: string;
}

Usage Examples:

import { Stack, Button, TextInput } from "@carbon/react";

// Vertical stack with consistent spacing
<Stack gap={4}>
  <h2>Contact Form</h2>
  <TextInput id="name" labelText="Name" />
  <TextInput id="email" labelText="Email" />
  <Button kind="primary">Submit</Button>
</Stack>

// Horizontal stack
<Stack orientation="horizontal" gap={2}>
  <Button kind="secondary">Cancel</Button>
  <Button kind="primary">Save</Button>
</Stack>

Navigation Components

Navigation elements including breadcrumbs, pagination, and content switching.

/**
 * Breadcrumb navigation component
 */
interface BreadcrumbProps {
  /** Breadcrumb items */
  children: React.ReactNode;
  /** Hide trailing slash */
  noTrailingSlash?: boolean;
  /** CSS class name */
  className?: string;
}

/**
 * Breadcrumb item component
 */
interface BreadcrumbItemProps extends React.ComponentPropsWithoutRef<"a"> {
  /** Item content */
  children: React.ReactNode;
  /** Item is current page */
  isCurrentPage?: boolean;
  /** CSS class name */
  className?: string;
}

/**
 * Content switcher for tab-like navigation
 */
interface ContentSwitcherProps {
  /** Selected index */
  selectedIndex?: number;
  /** Selection change handler */
  onChange?: (data: { index: number; name?: string; text?: string }) => void;
  /** Light theme */
  light?: boolean;
  /** Size variant */
  size?: "sm" | "md" | "lg";
  /** Content switcher children (Switch components) */
  children: React.ReactNode;
}

/**
 * Switch item for content switcher
 */
interface SwitchProps extends React.ComponentPropsWithoutRef<"button"> {
  /** Switch content */
  children: React.ReactNode;
  /** Switch name */
  name?: string;
  /** Switch text content */
  text?: string;
  /** Index in switcher */
  index?: number;
  /** Selected state */
  selected?: boolean;
}

/**
 * Pagination component
 */
interface PaginationProps {
  /** Total number of items */
  totalItems: number;
  /** Current page */
  page?: number;
  /** Items per page */
  pageSize?: number;
  /** Available page sizes */
  pageSizes?: number[];
  /** Page change handler */
  onChange?: (data: { page: number; pageSize: number }) => void;
  /** Page size change handler */
  onPageSizeChange?: (pageSize: number) => void;
  /** Backward button text */
  backwardText?: string;
  /** Forward button text */
  forwardText?: string;
  /** Items range text */
  itemRangeText?: (min: number, max: number, total: number) => string;
  /** Items text */
  itemsPerPageText?: string;
  /** Items text */
  itemText?: (min: number, max: number) => string;
  /** Page number text */
  pageNumberText?: string;
  /** Page range text */
  pageRangeText?: (current: number, total: number) => string;
  /** Page size input disabled */
  paginationInputDisabled?: boolean;
  /** Disabled state */
  disabled?: boolean;
  /** Size variant */
  size?: "sm" | "md" | "lg";
}

Usage Examples:

import { 
  Breadcrumb, 
  BreadcrumbItem, 
  ContentSwitcher, 
  Switch, 
  Pagination 
} from "@carbon/react";

// Breadcrumb navigation
<Breadcrumb>
  <BreadcrumbItem href="/">Home</BreadcrumbItem>
  <BreadcrumbItem href="/products">Products</BreadcrumbItem>
  <BreadcrumbItem href="/products/laptops">Laptops</BreadcrumbItem>
  <BreadcrumbItem isCurrentPage>MacBook Pro</BreadcrumbItem>
</Breadcrumb>

// Content switcher
<ContentSwitcher
  selectedIndex={activeTab}
  onChange={({ index }) => setActiveTab(index)}
>
  <Switch name="overview" text="Overview" />
  <Switch name="details" text="Details" />
  <Switch name="reviews" text="Reviews" />
</ContentSwitcher>

// Pagination
<Pagination
  totalItems={250}
  page={currentPage}
  pageSize={pageSize}
  pageSizes={[10, 20, 50, 100]}
  onChange={({ page, pageSize }) => {
    setCurrentPage(page);
    setPageSize(pageSize);
  }}
/>

Tab Navigation

Full-featured tab component with keyboard navigation and panel management.

/**
 * Tabs container component
 */
interface TabsProps {
  /** Default selected tab index */
  defaultSelectedIndex?: number;
  /** Selection change handler */
  onSelectionChange?: (index: number) => void;
  /** Tab children */
  children: React.ReactNode;
  /** Light theme */
  light?: boolean;
  /** Scrollable tabs */
  scrollIntoView?: boolean;
  /** Tabs type */
  type?: "default" | "container";
  /** Left panel overflow button ARIA label */
  leftOverflowButtonProps?: { "aria-label": string };
  /** Right panel overflow button ARIA label */
  rightOverflowButtonProps?: { "aria-label": string };
}

/**
 * Individual tab component
 */
interface TabProps extends React.ComponentPropsWithoutRef<"button"> {
  /** Tab label */
  children: React.ReactNode;
  /** Tab is disabled */
  disabled?: boolean;
  /** Tab href for link behavior */
  href?: string;
  /** Tab render icon */
  renderIcon?: React.ComponentType<any>;
  /** Tab is selected */
  selected?: boolean;
  /** Click handler */
  onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
}

/**
 * Tab panels container
 */
interface TabPanelsProps {
  /** Tab panels */
  children: React.ReactNode;
}

/**
 * Individual tab panel
 */
interface TabPanelProps {
  /** Panel content */
  children: React.ReactNode;
}

/**
 * Tab list container
 */
interface TabListProps {
  /** Tab list children */
  children: React.ReactNode;
  /** ARIA label */
  "aria-label"?: string;
  /** Light theme */
  light?: boolean;
  /** Contained variant */
  contained?: boolean;
  /** Activation mode */
  activation?: "automatic" | "manual";
}

Usage Examples:

import { Tabs, TabList, Tab, TabPanels, TabPanel } from "@carbon/react";
import { User, Settings, Notification } from "@carbon/react/icons";

<Tabs defaultSelectedIndex={0}>
  <TabList aria-label="Account settings">
    <Tab renderIcon={User}>Profile</Tab>
    <Tab renderIcon={Settings}>Settings</Tab>
    <Tab renderIcon={Notification}>Notifications</Tab>
  </TabList>
  <TabPanels>
    <TabPanel>
      <h3>Profile Settings</h3>
      <p>Manage your profile information...</p>
    </TabPanel>
    <TabPanel>
      <h3>Account Settings</h3>
      <p>Configure your account preferences...</p>
    </TabPanel>
    <TabPanel>
      <h3>Notification Settings</h3>
      <p>Control your notification preferences...</p>
    </TabPanel>
  </TabPanels>
</Tabs>

UI Shell Components

Complete application shell with header, navigation, and sidebar components.

/**
 * Application header component
 */
interface HeaderProps {
  /** Header children */
  children?: React.ReactNode;
  /** ARIA label */
  "aria-label"?: string;
  /** ARIA labelledby */
  "aria-labelledby"?: string;
  /** CSS class name */
  className?: string;
}

/**
 * Header name/brand component
 */
interface HeaderNameProps extends React.ComponentPropsWithoutRef<"a"> {
  /** Brand name content */
  children: React.ReactNode;
  /** Brand link href */
  href?: string;
  /** Prefix text */
  prefix?: string;
}

/**
 * Header navigation container
 */
interface HeaderNavigationProps {
  /** Navigation items */
  children: React.ReactNode;
  /** ARIA label */
  "aria-label"?: string;
  /** ARIA labelledby */
  "aria-labelledby"?: string;
}

/**
 * Header menu component
 */
interface HeaderMenuProps extends React.ComponentPropsWithoutRef<"li"> {
  /** Menu trigger text */
  menuLinkText: string;
  /** Menu items */
  children: React.ReactNode;
  /** ARIA label */
  "aria-label"?: string;
  /** ARIA labelledby */
  "aria-labelledby"?: string;
  /** Render icon */
  renderMenuIcon?: React.ComponentType<any>;
}

/**
 * Header menu item
 */
interface HeaderMenuItemProps extends React.ComponentPropsWithoutRef<"a"> {
  /** Menu item content */
  children: React.ReactNode;
  /** Item href */
  href?: string;
  /** Element to render */
  element?: React.ElementType;
}

/**
 * Side navigation component
 */
interface SideNavProps {
  /** Default expanded state */
  defaultExpanded?: boolean;
  /** Expanded state */
  expanded?: boolean;
  /** Fixed side nav */
  isFixedNav?: boolean;
  /** Large side nav */
  large?: boolean;
  /** Persistent side nav */
  isPersistent?: boolean;
  /** ARIA label */
  "aria-label"?: string;
  /** Side nav children */
  children: React.ReactNode;
  /** Toggle handler */
  onToggle?: (event: React.MouseEvent, expanded: boolean) => void;
}

/**
 * Side navigation item
 */
interface SideNavItemProps extends React.ComponentPropsWithoutRef<"a"> {
  /** Item content */
  children: React.ReactNode;
  /** Large variant */
  large?: boolean;
  /** Render icon */
  renderIcon?: React.ComponentType<any>;
  /** Item is active/current */
  isActive?: boolean;
}

/**
 * Side navigation menu (expandable)
 */
interface SideNavMenuProps {
  /** Menu title */
  title: string;
  /** Default expanded */
  defaultExpanded?: boolean;
  /** Expanded state */
  isExpanded?: boolean;
  /** Large variant */
  large?: boolean;
  /** Menu items */
  children: React.ReactNode;
  /** Render icon */
  renderIcon?: React.ComponentType<any>;
}

Usage Examples:

import {
  Header,
  HeaderContainer,
  HeaderName,
  HeaderNavigation,
  HeaderMenuItem,
  HeaderGlobalBar,
  HeaderGlobalAction,
  SideNav,
  SideNavItems,
  SideNavItem,
  SideNavMenu,
  SideNavMenuItem,
  SkipToContent
} from "@carbon/react";
import { 
  Notification, 
  UserAvatar, 
  Menu, 
  Dashboard, 
  Analytics 
} from "@carbon/react/icons";

<HeaderContainer
  render={({ isSideNavExpanded, onClickSideNavExpand }) => (
    <>
      <Header aria-label="IBM Platform">
        <SkipToContent />
        <HeaderMenuButton
          aria-label="Open menu"
          onClick={onClickSideNavExpand}
          isActive={isSideNavExpanded}
        />
        <HeaderName href="#" prefix="IBM">
          Product Name
        </HeaderName>
        <HeaderNavigation aria-label="Primary navigation">
          <HeaderMenuItem href="#">Dashboard</HeaderMenuItem>
          <HeaderMenuItem href="#">Analytics</HeaderMenuItem>
          <HeaderMenuItem href="#">Reports</HeaderMenuItem>
        </HeaderNavigation>
        <HeaderGlobalBar>
          <HeaderGlobalAction aria-label="Notifications">
            <Notification />
          </HeaderGlobalAction>
          <HeaderGlobalAction aria-label="User profile">
            <UserAvatar />
          </HeaderGlobalAction>
        </HeaderGlobalBar>
        <SideNav
          aria-label="Side navigation"
          expanded={isSideNavExpanded}
          isPersistent={false}
        >
          <SideNavItems>
            <SideNavItem renderIcon={Dashboard} href="#">
              Dashboard
            </SideNavItem>
            <SideNavMenu renderIcon={Analytics} title="Analytics">
              <SideNavMenuItem href="#">Reports</SideNavMenuItem>
              <SideNavMenuItem href="#">Insights</SideNavMenuItem>
              <SideNavMenuItem href="#">Metrics</SideNavMenuItem>
            </SideNavMenu>
          </SideNavItems>
        </SideNav>
      </Header>
    </>
  )}
/>

Link Components

Link elements with proper styling and accessibility support.

/**
 * Link component with Carbon styling
 */
interface LinkProps extends React.ComponentPropsWithoutRef<"a"> {
  /** Link content */
  children: React.ReactNode;
  /** Disabled state */
  disabled?: boolean;
  /** Inline variant */
  inline?: boolean;
  /** Link size */
  size?: "sm" | "md" | "lg";
  /** Visited state styling */
  visited?: boolean;
  /** Render icon */
  renderIcon?: React.ComponentType<any>;
}

Usage Examples:

import { Link } from "@carbon/react";
import { Launch } from "@carbon/react/icons";

// Basic link
<Link href="/documentation">View documentation</Link>

// Link with icon
<Link href="https://example.com" renderIcon={Launch}>
  External link
</Link>

// Disabled link
<Link href="#" disabled>
  Disabled link
</Link>

Layer & Theme Context

/**
 * Layer context provider for nested components
 */
interface LayerProps {
  /** Layer children */
  children: React.ReactNode;
  /** Layer level (0-2) */
  level?: number;
  /** CSS class name */
  className?: string;
}

/**
 * Aspect ratio container for media
 */
interface AspectRatioProps {
  /** Container children */
  children: React.ReactNode;
  /** Aspect ratio (e.g., "16x9", "4x3", "2x1", "1x2", "1x1") */
  ratio?: "16x9" | "9x16" | "2x1" | "1x2" | "4x3" | "3x4" | "1x1";
  /** CSS class name */
  className?: string;
}

Version

Tile

Files