@waysnx/ui-layout

Layout components from WaysNX - comprehensive set of layout utilities and components.

Installation

npm install @waysnx/ui-layout

This is a standalone package — no dependency on @waysnx/ui-core. Only requires react >= 18 as a peer dependency.

📖 Installation Guide — See all available packages and choose the right one for your needs.

Components

Page Structure

• PageLayout - Main page container
• SidebarLayout - Layout with collapsible sidebar
• PageHeader - Page header section
• PageContent - Main content area
• Container - Responsive container with max-width
• Section - Semantic section wrapper

Layout Utilities

• Grid - CSS Grid layout
• Row - Flexbox row container
• Column - Flexbox column container
• Stack - Vertical/horizontal stack with spacing
• Divider - Visual separator
• Spacer - Flexible spacing element

Content Organization

• Card - Content card with optional header/footer
• Panel - Content panel with title
• Tabs - Tabbed interface (TabList, Tab, TabPanels, TabPanel)
• Accordion - Collapsible sections (AccordionItem)
• Collapsible - Single collapsible section
• SplitLayout - Resizable split panes

Navigation Layout

• Breadcrumb - Navigation breadcrumb trail
• Stepper - Step-by-step progress indicator
• PageTabs - Page-level tab navigation
• Wizard - Multi-step form wizard with validation

Usage Examples

Accessibility

Layout components include built-in ARIA roles and attributes. Some components expose additional props for accessibility customization:

| Component | Prop | Type | Description | |-----------|------|------|-------------| | Card | title | string | Sets aria-label on the card's <article> element and renders an <h3> heading | | Stepper | label | string | Sets aria-label on the role="progressbar" element (default: "Progress") | | Tabs | label | string | Sets aria-label on the tab container | | TabList | label | string | Sets aria-label on the role="tablist" element |

// Card with accessible label
<Card title="User Profile">
  <p>Card content</p>
</Card>

// Stepper with custom label
<Stepper
  label="Order checkout progress"
  currentStep={1}
  steps={[...]}
/>

// Tabs with accessible label
<Tabs label="Product details">
  <TabList label="Product sections">
    <Tab>Description</Tab>
    <Tab>Reviews</Tab>
  </TabList>
  ...
</Tabs>

Note: Accordion keyboard navigation (Enter/Space to toggle), Wizard step management, and Stepper role="progressbar" with aria-valuenow/min/max are all handled automatically.

Basic Page Layout

import { PageLayout, SidebarLayout, PageHeader, PageContent } from '@waysnx/ui-layout';
import '@waysnx/ui-layout/dist/styles/index.css';

function App() {
  return (
    <PageLayout>
      <SidebarLayout
        collapsible
        sidebar={<div>Navigation Menu</div>}
      >
        <PageHeader>
          <h1>Dashboard</h1>
        </PageHeader>
        <PageContent>
          <p>Your content here</p>
        </PageContent>
      </SidebarLayout>
    </PageLayout>
  );
}

Grid Layout

import { Grid, Card } from '@waysnx/ui-layout';

function Dashboard() {
  return (
    <Grid columns={3} gap="1rem">
      <Card title="Card 1">Content</Card>
      <Card title="Card 2">Content</Card>
      <Card title="Card 3">Content</Card>
    </Grid>
  );
}

Tabs

import { TabList, Tab, TabPanels, TabPanel } from '@waysnx/ui-layout';
import { useState } from 'react';

function TabsExample() {
  const [activeTab, setActiveTab] = useState(0);
  
  return (
    <>
      <TabList activeTab={activeTab} onTabChange={setActiveTab}>
        <Tab>Tab 1</Tab>
        <Tab>Tab 2</Tab>
      </TabList>
      <TabPanels activeTab={activeTab}>
        <TabPanel>Content 1</TabPanel>
        <TabPanel>Content 2</TabPanel>
      </TabPanels>
    </>
  );
}

Breadcrumb

import { Breadcrumb } from '@waysnx/ui-layout';

function BreadcrumbExample() {
  return (
    <Breadcrumb
      items={[
        { label: 'Home', href: '/' },
        { label: 'Products', href: '/products' },
        { label: 'Details' }
      ]}
    />
  );
}

Stepper

import { Stepper } from '@waysnx/ui-layout';

function StepperExample() {
  return (
    <Stepper
      currentStep={1}
      steps={[
        { label: 'Step 1', description: 'First step' },
        { label: 'Step 2', description: 'Second step' },
        { label: 'Step 3', description: 'Final step' }
      ]}
    />
  );
}

Split Layout

import { SplitLayout } from '@waysnx/ui-layout';

function SplitExample() {
  return (
    <SplitLayout direction="horizontal" initialSize={30}>
      <div>Sidebar</div>
      <div>Main Content</div>
    </SplitLayout>
  );
}

Wizard

import { Wizard, WizardStep } from '@waysnx/ui-layout';

function WizardExample() {
  return (
    <Wizard onComplete={() => console.log('Completed!')}>
      <WizardStep
        id="step1"
        title="Account"
        description="Create your account"
        validate={() => {
          // Return true if valid, false otherwise
          return true;
        }}
      >
        <AccountForm />
      </WizardStep>
      <WizardStep
        id="step2"
        title="Profile"
        description="Setup your profile"
        canSkip
      >
        <ProfileForm />
      </WizardStep>
      <WizardStep
        id="step3"
        title="Review"
        description="Review and confirm"
      >
        <ReviewStep />
      </WizardStep>
    </Wizard>
  );
}

Wizard Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | onComplete | () => void | - | Called when the last step is submitted | | onStepChange | (step: number) => void | - | Called on every step change | | defaultStep | number | 0 | Initial step index | | showStepNumbers | boolean | true | Show step numbers in circles | | theme | 'default' \| 'minimal' \| 'modern' | 'default' | Visual theme | | layout | 'horizontal' \| 'vertical' | 'horizontal' | Step indicator orientation | | saveProgress | boolean | false | Show "Save & Continue Later" button | | onSaveProgress | (stepIndex: number) => void | - | Called when save button is clicked | | submitButtonText | string | 'Finish' | Label for the final step submit button | | successMessage | string | - | Message shown after successful completion | | errorMessage | string | - | Message shown when step validation fails | | className | string | '' | Additional CSS class |

Themes

// Default — standard styling
<Wizard theme="default" onComplete={() => {}}>...</Wizard>

// Minimal — clean, borderless, ghost buttons
<Wizard theme="minimal" onComplete={() => {}}>...</Wizard>

// Modern — gradients, shadows, pill-shaped buttons
<Wizard theme="modern" onComplete={() => {}}>...</Wizard>

Vertical Layout

<Wizard layout="vertical" onComplete={() => {}}>
  <WizardStep id="s1" title="Account" description="Create account">...</WizardStep>
  <WizardStep id="s2" title="Profile" description="Setup profile">...</WizardStep>
</Wizard>

Save Progress, Custom Submit Text, Success & Error Messages

<Wizard
  submitButtonText="Submit Application"
  saveProgress
  onSaveProgress={(step) => saveToLocalStorage(step)}
  successMessage="Application submitted successfully!"
  errorMessage="Please fill in all required fields."
  onComplete={() => submitToApi()}
>
  <WizardStep
    id="s1"
    title="Details"
    validate={() => validateForm()}
  >
    <MyForm />
  </WizardStep>
</Wizard>

Styling

Import the CSS file in your app:

import '@waysnx/ui-layout/dist/styles/index.css';

All layout components use CSS variables with the --wx- prefix for easy theming:

:root {
  --wx-color-primary: #f19924;       /* Active tabs, stepper, wizard */
  --wx-color-primary-hover: #e08916;
  --wx-color-primary-contrast: #fff;
  --wx-color-text: #1e293b;
  --wx-color-text-muted: #64748b;
  --wx-color-surface: #ffffff;
  --wx-color-surface-alt: #f8fafc;
  --wx-color-border: #e2e8f0;
}

These are the same variables used across all WaysNX libraries. See the Theming Guide for the full list.

TypeScript Support

Full TypeScript support with exported types:

import type {
  PageLayoutProps,
  SidebarLayoutProps,
  GridProps,
  CardProps,
  TabListProps,
  AccordionProps,
  BreadcrumbProps,
  StepperProps,
  WizardProps,
  WizardStepProps,
  SplitLayoutProps,
} from '@waysnx/ui-layout';

Peer Dependencies

• react >= 18

Links

• npm Package: @waysnx/ui-layout

License

MIT © WaysNX Technologies