Creating Components

Guide to creating new components for Mintlify Components

This guide walks you through creating a new component for the Mintlify Components library.

Component Guidelines

When adding or modifying components, ensure they meet these requirements:

• React Compatibility: Ensure compatibility with React 18 and 19
• Theming: Support both light and dark themes
• Accessibility: Include ARIA attributes and keyboard navigation
• Documentation: Add Storybook stories documenting usage
• TypeScript: Export types for TypeScript users

Creating a New Component

1. Create component directory

   Create a new directory under packages/components/src/components/:

   mkdir packages/components/src/components/YourComponent
   
2. Implement the component

   Create your component file with TypeScript:

   packages/components/src/components/YourComponent/YourComponent.tsx

   import React from 'react';
   
   export interface YourComponentProps {
     // Define your props here
     title: string;
     children?: React.ReactNode;
   }
   
   export const YourComponent: React.FC<YourComponentProps> = ({
     title,
     children,
   }) => {
     return (
       <div className="your-component">
         <h2>{title}</h2>
         {children}
       </div>
     );
   };
   
3. Export the component

   Add your component to packages/components/src/components/index.ts:

   export { YourComponent } from './YourComponent/YourComponent';
   export type { YourComponentProps } from './YourComponent/YourComponent';
   
4. Create a Storybook story

   Create a story file for documentation:

   packages/components/src/components/YourComponent/YourComponent.stories.tsx

   import type { Meta, StoryObj } from '@storybook/react';
   import { YourComponent } from './YourComponent';
   
   const meta: Meta<typeof YourComponent> = {
     title: 'Components/YourComponent',
     component: YourComponent,
     tags: ['autodocs'],
   };
   
   export default meta;
   type Story = StoryObj<typeof YourComponent>;
   
   export const Default: Story = {
     args: {
       title: 'Hello World',
     },
   };
   
5. Verify the build

   Run the build to ensure everything compiles:

   pnpm build
   
6. Test in Storybook

   Start Storybook and verify your component:

   pnpm storybook
   

   Navigate to http://localhost:6006 to see your component.

Styling with Tailwind CSS

Use Tailwind CSS utility classes for styling:

export const YourComponent: React.FC<YourComponentProps> = ({ title }) => {
  return (
    <div className="rounded-lg bg-white p-4 shadow-md dark:bg-gray-800">
      <h2 className="text-xl font-semibold text-gray-900 dark:text-white">
        {title}
      </h2>
    </div>
  );
};

Accessibility Best Practices

Make your components accessible:

export const YourComponent: React.FC<YourComponentProps> = ({
  title,
  onClose,
}) => {
  return (
    <div role="dialog" aria-labelledby="component-title">
      <h2 id="component-title">{title}</h2>
      <button
        onClick={onClose}
        aria-label="Close dialog"
        className="close-button"
      >
        ×
      </button>
    </div>
  );
};

TypeScript Types

Always export TypeScript types for your components:

export interface YourComponentProps {
  /** The title to display */
  title: string;
  /** Optional callback when closed */
  onClose?: () => void;
  /** Additional CSS classes */
  className?: string;
}

Testing Your Component

Before submitting:

• Test in both light and dark themes
• Verify keyboard navigation works
• Check screen reader compatibility
• Test with React 18 and 19
• Ensure all props are documented in Storybook

Next Steps

• Review the development workflow
• Read the contributing guidelines
• Submit your changes via pull request