mdxui

Testimonials Section

Customer testimonials and social proof component

Testimonials Section

The <Testimonials> section displays customer quotes, reviews, and social proof. It builds trust and credibility by showing real experiences from satisfied customers.

Interface

import type { TestimonialsProps } from 'mdxui'

interface TestimonialsProps {
  /** Section title */
  title?: string
  /** Testimonial items */
  testimonials: Testimonial[]
  /** Layout variant */
  variant?: 'grid' | 'carousel' | 'masonry'
}

interface Testimonial {
  /** Quote text */
  quote: string
  /** Author name */
  author: string
  /** Author title/role */
  title?: string
  /** Author company */
  company?: string
  /** Author avatar URL */
  avatar?: string
}

Usage

Basic Example

import { Testimonials } from '@mdxui/beacon'

<Testimonials
  testimonials={[
    {
      quote: "mdxui helped us ship our SaaS product in weeks instead of months. The type-safe components just work.",
      author: "Sarah Chen",
      title: "CTO",
      company: "Acme Corp"
    },
    {
      quote: "The best React component library I've used. Everything is well-documented and intuitive.",
      author: "Alex Kumar",
      title: "Lead Developer",
      company: "TechStart"
    }
  ]}
/>

With Title

<Testimonials
  title="Loved by developers worldwide"
  testimonials={[...]}
/>

With Avatars

<Testimonials
  title="What our customers say"
  testimonials={[
    {
      quote: "Switching to mdxui was the best decision we made this year.",
      author: "Emily Rodriguez",
      title: "Product Manager",
      company: "StartupXYZ",
      avatar: "/avatars/emily.jpg"
    },
    {
      quote: "The auto-wiring feature saved us weeks of development time.",
      author: "James Wilson",
      title: "Engineering Lead",
      company: "ScaleHub",
      avatar: "/avatars/james.jpg"
    }
  ]}
/>

Grid Layout

<Testimonials
  variant="grid"
  title="Trusted by thousands"
  testimonials={[
    {
      quote: "mdxui components are production-ready out of the box. No more building everything from scratch.",
      author: "Lisa Park",
      company: "DevTools Inc"
    },
    {
      quote: "The TypeScript support is incredible. Catch errors before they reach production.",
      author: "Michael Torres",
      company: "CloudSoft"
    },
    {
      quote: "Finally, a component library that actually understands developer needs.",
      author: "Priya Sharma",
      company: "CodeCraft"
    }
  ]}
/>
<Testimonials
  variant="carousel"
  title="Customer success stories"
  testimonials={[
    {
      quote: "We built our entire marketing site in one weekend using mdxui. The components are beautiful and flexible.",
      author: "David Kim",
      title: "Founder & CEO",
      company: "LaunchFast",
      avatar: "/avatars/david.jpg"
    },
    {
      quote: "The documentation is so good that even our junior developers can use mdxui effectively.",
      author: "Rachel Green",
      title: "Engineering Manager",
      company: "BuildRight"
    }
  ]}
/>

Masonry Layout

<Testimonials
  variant="masonry"
  testimonials={[
    {
      quote: "Great library!",
      author: "John Doe"
    },
    {
      quote: "mdxui transformed how we build web applications. The component templates saved us countless hours of development time.",
      author: "Maria Garcia",
      title: "Technical Lead"
    },
    {
      quote: "Best investment we made.",
      author: "Tom Brown",
      company: "TechCo"
    }
  ]}
/>

Props

title (optional)

Type: string

Section heading displayed above testimonials.

<Testimonials
  title="What developers are saying"
  testimonials={[...]}
/>

testimonials (required)

Type: Testimonial[]

Array of testimonial objects.

interface Testimonial {
  quote: string           // The testimonial text
  author: string          // Customer name
  title?: string          // Job title or role
  company?: string        // Company name
  avatar?: string         // Profile photo URL
}

<Testimonials
  testimonials={[
    {
      quote: "Amazing product!",
      author: "Jane Smith",
      title: "Product Designer",
      company: "Design Co",
      avatar: "/avatars/jane.jpg"
    }
  ]}
/>

variant (optional)

Type: 'grid' | 'carousel' | 'masonry' Default: 'grid'

Controls the layout style.

// Grid: Equal-sized cards in a grid
<Testimonials variant="grid" />

// Carousel: Sliding testimonials
<Testimonials variant="carousel" />

// Masonry: Pinterest-style layout
<Testimonials variant="masonry" />

Testimonial Props

quote (required)

Type: string

The testimonial text. Keep it authentic and specific.

{
  quote: "mdxui helped us ship 3x faster than our previous stack"
}

Best practices:

  • Keep it concise (1-3 sentences)
  • Be specific (mention features, benefits)
  • Use authentic language
  • Avoid marketing speak

author (required)

Type: string

Full name of the person giving the testimonial.

{ author: "Sarah Johnson" }
{ author: "Alex Chen" }

title (optional)

Type: string

Job title or role of the person.

{ title: "CTO" }
{ title: "Lead Developer" }
{ title: "Product Manager" }

company (optional)

Type: string

Company or organization name.

{ company: "Acme Corp" }
{ company: "StartupXYZ" }

avatar (optional)

Type: string

URL to profile photo.

{ avatar: "/avatars/sarah.jpg" }
{ avatar: "https://example.com/photo.jpg" }

Image requirements:

  • Square aspect ratio (1:1)
  • Minimum 200x200px
  • Optimized file size (< 100KB)
  • Use WebP format if possible

Variants in Detail

Grid Variant

Traditional card grid with equal-sized testimonials.

<Testimonials
  variant="grid"
  title="Trusted by industry leaders"
  testimonials={[
    {
      quote: "The best component library we've ever used. Clean, fast, and well-documented.",
      author: "Emma Watson",
      title: "VP of Engineering",
      company: "TechCorp",
      avatar: "/avatars/emma.jpg"
    },
    {
      quote: "mdxui made our development process so much smoother. Highly recommend!",
      author: "Liam Chen",
      title: "Senior Developer",
      company: "DevShop"
    },
    {
      quote: "Finally, components that actually work as advertised. No surprises.",
      author: "Olivia Martinez",
      title: "Tech Lead",
      company: "BuildFast"
    }
  ]}
/>

Best for:

  • 3-6 testimonials
  • Equal-length quotes
  • Professional layouts

Sliding testimonials with navigation controls.

<Testimonials
  variant="carousel"
  title="Customer success stories"
  testimonials={[
    {
      quote: "We migrated our entire app to mdxui in just two weeks. The transition was seamless and our customers loved the new UI.",
      author: "Noah Williams",
      title: "CTO",
      company: "MigrateApp",
      avatar: "/avatars/noah.jpg"
    },
    {
      quote: "The support team is incredible. They helped us customize components to match our exact needs.",
      author: "Sophia Lee",
      title: "Engineering Manager",
      company: "SupportFirst"
    }
  ]}
/>

Best for:

  • 5+ testimonials
  • Longer quotes
  • Highlighting one at a time

Masonry Layout

Pinterest-style layout with varying card heights.

<Testimonials
  variant="masonry"
  testimonials={[
    {
      quote: "Great!",
      author: "Quick Review"
    },
    {
      quote: "We've been using mdxui for 6 months and it's transformed our workflow. The type safety catches bugs early, the components are flexible, and the documentation is top-notch.",
      author: "Isabella Brown",
      title: "Lead Architect"
    },
    {
      quote: "Worth every penny.",
      author: "Mason Davis",
      company: "ValueSeeker"
    }
  ]}
/>

Best for:

  • Varying quote lengths
  • Visual interest
  • Many testimonials (6+)

Implementation Details

The reference implementation from @mdxui/beacon includes:

Features

  • Responsive Grid - Adapts to screen size
  • Avatar Display - Optional profile photos
  • Quote Styling - Quotation marks and styling
  • Smooth Animations - Fade-in effects
  • Carousel Controls - Previous/next buttons for carousel
  • Accessibility - Proper ARIA labels

Structure

<section className="testimonials">
  {title && (
    <div className="testimonials-header">
      <h2>{title}</h2>
    </div>
  )}

  <div className={`testimonials-${variant}`}>
    {testimonials.map((testimonial, index) => (
      <blockquote key={index} className="testimonial">
        {testimonial.avatar && (
          <img
            src={testimonial.avatar}
            alt={testimonial.author}
            className="avatar"
          />
        )}

        <p className="quote">{testimonial.quote}</p>

        <footer className="attribution">
          <cite className="author">{testimonial.author}</cite>
          {testimonial.title && (
            <span className="title">{testimonial.title}</span>
          )}
          {testimonial.company && (
            <span className="company">{testimonial.company}</span>
          )}
        </footer>
      </blockquote>
    ))}
  </div>
</section>

Real-World Examples

SaaS Product Testimonials

<Testimonials
  title="Join thousands of satisfied customers"
  variant="grid"
  testimonials={[
    {
      quote: "Our team's productivity increased by 40% after switching to this platform. The automation features alone saved us 10 hours per week.",
      author: "Amanda Foster",
      title: "Operations Director",
      company: "ProductivityPro",
      avatar: "/testimonials/amanda.jpg"
    },
    {
      quote: "Best customer support I've experienced. They helped us migrate all our data and were available 24/7 during the transition.",
      author: "Carlos Rivera",
      title: "IT Manager",
      company: "MigrateEasy"
    },
    {
      quote: "The ROI was clear within the first month. We've since expanded to 3 additional teams.",
      author: "Jennifer Kim",
      title: "VP of Finance",
      company: "ROIFocus",
      avatar: "/testimonials/jennifer.jpg"
    },
    {
      quote: "Simple, powerful, and reliable. Everything we needed in one platform.",
      author: "Marcus Johnson",
      title: "CTO",
      company: "SimpleTech"
    }
  ]}
/>

Developer Tool Testimonials

<Testimonials
  variant="carousel"
  title="What developers are saying"
  testimonials={[
    {
      quote: "I've been using this for all my side projects. The DX is incredible - hot reload works perfectly and the error messages are actually helpful.",
      author: "Sophie Anderson",
      title: "Full Stack Developer",
      avatar: "/testimonials/sophie.jpg"
    },
    {
      quote: "Finally, a tool that doesn't get in my way. I can focus on building features instead of fighting with configuration.",
      author: "Ryan Patel",
      title: "Senior Engineer",
      company: "BuildFast"
    },
    {
      quote: "The documentation is so good that I rarely need to look elsewhere. Everything is explained clearly with great examples.",
      author: "Elena Volkov",
      title: "Frontend Lead",
      company: "DocLove"
    }
  ]}
/>

E-commerce Testimonials

<Testimonials
  title="Customer reviews"
  variant="masonry"
  testimonials={[
    {
      quote: "Love it!",
      author: "Happy Customer",
      avatar: "/testimonials/customer1.jpg"
    },
    {
      quote: "Received my order in 2 days and the quality exceeded my expectations. The packaging was beautiful and everything was exactly as described.",
      author: "Michelle Robinson",
      company: "FastShip Customer"
    },
    {
      quote: "Great product, great price.",
      author: "Tom Baker"
    },
    {
      quote: "I've ordered three times now and every experience has been perfect. Customer service is responsive and helpful.",
      author: "Lisa Wong",
      avatar: "/testimonials/lisa.jpg"
    }
  ]}
/>

Quote Formatting

Quotation Marks

The reference implementation adds visual quotation marks:

<blockquote className="testimonial">
  <p className="quote">
    <span className="quote-mark">"</span>
    {testimonial.quote}
    <span className="quote-mark">"</span>
  </p>
</blockquote>

CSS:

.quote-mark {
  font-size: 2em;
  color: var(--color-primary);
  opacity: 0.5;
}

Attribution

Format author information consistently:

<footer className="attribution">
  <cite>{author}</cite>
  {title && company ? (
    <span>{title} at {company}</span>
  ) : title ? (
    <span>{title}</span>
  ) : company ? (
    <span>{company}</span>
  ) : null}
</footer>

Accessibility

The reference implementation includes:

  • Semantic HTML - Uses <blockquote>, <cite>, <footer>
  • ARIA Labels - Proper labeling for screen readers
  • Alt Text - Descriptive alt text for avatars
  • Keyboard Navigation - Arrow keys for carousel
  • Focus Management - Visible focus indicators
<section className="testimonials" aria-labelledby="testimonials-title">
  <h2 id="testimonials-title">{title}</h2>

  <div className="testimonials-grid" role="list">
    {testimonials.map((testimonial, i) => (
      <blockquote
        key={i}
        className="testimonial"
        role="listitem"
      >
        {testimonial.avatar && (
          <img
            src={testimonial.avatar}
            alt={`${testimonial.author}, ${testimonial.title || 'Customer'}`}
            className="avatar"
          />
        )}

        <p className="quote">{testimonial.quote}</p>

        <footer>
          <cite>{testimonial.author}</cite>
          {testimonial.title && <span>, {testimonial.title}</span>}
          {testimonial.company && <span> at {testimonial.company}</span>}
        </footer>
      </blockquote>
    ))}
  </div>
</section>

Best Practices

Gathering Testimonials

  • Ask specific questions: "What problem did we solve?"
  • Get permission: Always ask before publishing
  • Include details: Name, title, company
  • Use photos: Real photos build trust
  • Update regularly: Keep testimonials fresh

Writing Guidelines

  • Be authentic: Real quotes > edited perfection
  • Show specifics: Numbers, metrics, features
  • Vary length: Mix short and detailed
  • Address objections: Include common concerns
  • Highlight benefits: Focus on outcomes

Selection

  • Choose diverse: Different roles, companies, use cases
  • Lead with strong: Best testimonial first
  • Include metrics: "40% faster" > "very fast"
  • Show use cases: Different customer types
  • Rotate regularly: Update quarterly

Visual Design

  • Use avatars: People trust faces
  • Keep it scannable: Highlight key phrases
  • Add company logos: Builds credibility
  • Use quotes: Visual quotation marks
  • Consistent styling: Same card design

Implementation

For carousel variant, add navigation controls:

const [currentIndex, setCurrentIndex] = useState(0)

const next = () => {
  setCurrentIndex((i) => (i + 1) % testimonials.length)
}

const prev = () => {
  setCurrentIndex((i) =>
    i === 0 ? testimonials.length - 1 : i - 1
  )
}

<div className="carousel-controls">
  <button onClick={prev} aria-label="Previous testimonial">
    <ChevronLeft />
  </button>
  <button onClick={next} aria-label="Next testimonial">
    <ChevronRight />
  </button>
</div>

Auto-play

Optional auto-advance feature:

useEffect(() => {
  const interval = setInterval(() => {
    setCurrentIndex((i) => (i + 1) % testimonials.length)
  }, 5000) // 5 seconds

  return () => clearInterval(interval)
}, [testimonials.length])

Composition

In LandingPage

Testimonials typically follow pricing:

<LandingPage>
  <Hero {...heroProps} />
  <Features {...featuresProps} />
  <Pricing {...pricingProps} />
  <Testimonials {...testimonialsProps} />
  <FAQ {...faqProps} />
  <CTA {...ctaProps} />
</LandingPage>

With CTA

Combine with CTA for conversion:

<Testimonials {...testimonialsProps} />
<CTA
  title="Join thousands of happy customers"
  cta={{ text: "Start Free Trial", href: "/signup" }}
/>

TypeScript

Full type definitions:

import { z } from 'zod'
import type { Component } from 'mdxui'

export const TestimonialSchema = z.object({
  quote: z.string(),
  author: z.string(),
  title: z.string().optional(),
  company: z.string().optional(),
  avatar: z.string().optional(),
})

export const TestimonialsPropsSchema = z.object({
  title: z.string().optional(),
  testimonials: z.array(TestimonialSchema),
  variant: z.enum(['grid', 'carousel', 'masonry']).default('grid'),
})

export type Testimonial = z.infer<typeof TestimonialSchema>
export type TestimonialsProps = z.infer<typeof TestimonialsPropsSchema>
export type Testimonials = Component<TestimonialsProps>

On this page