vue

Vue Component Patterns

Overview

Build accessible, token-driven Vue 3 components using Composition API and modern patterns. Covers SFC structure, TypeScript integration, composables, and consuming design tokens.

When to Use

• Creating a Vue 3 component library
• Building components that use design tokens
• Setting up a design system in Vue/Nuxt
• Converting designs to Vue components

The Process

1. Identify component type: Primitive, composite, or layout?
2. Choose styling approach: Scoped CSS, CSS Modules, Tailwind, or UnoCSS?
3. Define props with TypeScript: Use defineProps with interfaces
4. Implement with tokens: CSS custom properties or provide/inject
5. Add accessibility: ARIA, keyboard handling, focus management
6. Create composables: Extract reusable logic

Project Structure

src/
├── components/
│   ├── primitives/
│   │   ├── VButton/
│   │   │   ├── VButton.vue
│   │   │   ├── VButton.test.ts
│   │   │   └── index.ts
│   │   ├── VInput/
│   │   └── VText/
│   ├── composite/
│   │   ├── VCard/
│   │   ├── VModal/
│   │   └── VDropdown/
│   └── layout/
│       ├── VStack/
│       ├── VGrid/
│       └── VContainer/
├── composables/
│   ├── useTheme.ts
│   ├── useBreakpoint.ts
│   └── useId.ts
├── tokens/
│   └── index.css
└── index.ts

Component Patterns

Button Component

VButton.vue:

<script setup lang="ts">
import { computed, useSlots } from 'vue';

export interface ButtonProps {
  /** Visual style variant */
  variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
  /** Size of the button */
  size?: 'sm' | 'md' | 'lg';
  /** Full width button */
  fullWidth?: boolean;
  /** Loading state */
  loading?: boolean;
  /** Disabled state */
  disabled?: boolean;
  /** HTML button type */
  type?: 'button' | 'submit' | 'reset';
}

const props = withDefaults(defineProps<ButtonProps>(), {
  variant: 'primary',
  size: 'md',
  fullWidth: false,
  loading: false,
  disabled: false,
  type: 'button',
});

const emit = defineEmits<{
  click: [event: MouseEvent];
}>();

const slots = useSlots();

const isDisabled = computed(() => props.disabled || props.loading);

const classes = computed(() => [
  'btn',
  `btn--${props.variant}`,
  `btn--${props.size}`,
  {
    'btn--full-width': props.fullWidth,
    'btn--loading': props.loading,
  },
]);

function handleClick(event: MouseEvent) {
  if (!isDisabled.value) {
    emit('click', event);
  }
}
</script>

<template>
  <button
    :type="type"
    :class="classes"
    :disabled="isDisabled"
    :aria-busy="loading"
    @click="handleClick"
  >
    <span v-if="loading" class="btn__spinner" aria-hidden="true" />
    <span v-if="slots.leftIcon" class="btn__icon">
      <slot name="leftIcon" />
    </span>
    <span class="btn__label">
      <slot />
    </span>
    <span v-if="slots.rightIcon" class="btn__icon">
      <slot name="rightIcon" />
    </span>
  </button>
</template>

<style scoped>
.btn {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: var(--spacing-xs);
  font-family: inherit;
  font-weight: 500;
  line-height: 1;
  white-space: nowrap;
  cursor: pointer;
  user-select: none;
  border: 1px solid transparent;
  border-radius: var(--radius-md);
  transition:
    background-color 150ms ease,
    border-color 150ms ease,
    transform 100ms ease;
}

.btn:focus-visible {
  outline: 2px solid var(--color-primary-500);
  outline-offset: 2px;
}

.btn:active:not(:disabled) {
  transform: scale(0.98);
}

.btn:disabled {
  cursor: not-allowed;
  opacity: 0.5;
}

/* Variants */
.btn--primary {
  background-color: var(--color-primary-500);
  color: white;
}

.btn--primary:hover:not(:disabled) {
  background-color: var(--color-primary-600);
}

.btn--secondary {
  background-color: transparent;
  border-color: var(--color-gray-300);
  color: var(--color-gray-700);
}

.btn--secondary:hover:not(:disabled) {
  background-color: var(--color-gray-50);
  border-color: var(--color-gray-400);
}

.btn--ghost {
  background-color: transparent;
  color: var(--color-gray-700);
}

.btn--ghost:hover:not(:disabled) {
  background-color: var(--color-gray-100);
}

.btn--danger {
  background-color: var(--color-error-500);
  color: white;
}

.btn--danger:hover:not(:disabled) {
  background-color: var(--color-error-600);
}

/* Sizes */
.btn--sm {
  height: 32px;
  padding: 0 var(--spacing-sm);
  font-size: var(--text-sm);
}

.btn--md {
  height: 40px;
  padding: 0 var(--spacing-md);
  font-size: var(--text-base);
}

.btn--lg {
  height: 48px;
  padding: 0 var(--spacing-lg);
  font-size: var(--text-lg);
}

/* Modifiers */
.btn--full-width {
  width: 100%;
}

.btn--loading .btn__label {
  opacity: 0;
}

.btn__spinner {
  position: absolute;
  width: 1em;
  height: 1em;
  border: 2px solid currentColor;
  border-right-color: transparent;
  border-radius: 50%;
  animation: spin 600ms linear infinite;
}

@keyframes spin {
  to {
    transform: rotate(360deg);
  }
}

.btn__icon {
  display: flex;
  flex-shrink: 0;
}
</style>