Vue 3 Simple Component Development: API Design from the Button Component

Minimalism is not crudeness, restraint is not deficiency — drawing inspiration from Nuxt UI v4, how to design a well-crafted component API

This article covers: Props definition, variant system (variant + color), size trade-offs (why remove xs/xl), slot design (label prop vs default slot), loading state handling (including CLS prevention), accessibility attributes, and a comparison table with mainstream UI libraries.

I. Background and Reference

In previous articles, we discussed the concept of design tokens over atomic CSS, and the architecture of CSS-first + thin component wrappers. But one question remains unanswered: How should a single component’s API be designed?

Early in the design process, I deeply referenced Nuxt UI v4’s approach. Nuxt UI v4 consolidates complex styles and interactions into a few core dimensions — variant/color/size. This is exactly what I wanted: encapsulate complexity inside the component, exposing only the most streamlined API to the outside.

This article uses the Button component as an example to walk through my design trade-offs and thought process step by step.

II. Starting from Requirements: What Does a Button Need?

A button component’s most basic functionality:

• Display text
• Trigger events on click
• Disabled state
• Different styles (primary, secondary, danger, etc.)

But is that enough? Let’s look at real usage scenarios:

<!-- Button with icon -->
<Button>
  <template #icon>🔍</template>
  Search
</Button>

<!-- Loading state -->
<Button loading>Submitting</Button>

<!-- Block button (full width) -->
<Button block>Full Width Button</Button>

<!-- Different sizes -->
<Button size="sm">Small</Button>

Enter fullscreen mode Exit fullscreen mode

After analysis, the Button component needs to support:

Requirement Implementation Text content Default slot or label prop Click event click event Disabled state disabled prop Loading state loading prop Different styles variant + color Different sizes size prop Block width block prop Icon #icon slot

III. Props Design: Types, Defaults, Priority

3.1 Base Props

interface Props {
  label?: string;      // Button text
  disabled?: boolean;  // Disabled state
  loading?: boolean;   // Loading state
  block?: boolean;     // Block level
}

Enter fullscreen mode Exit fullscreen mode

Default value design:

const props = withDefaults(defineProps<Props>(), {
  label: "",
  disabled: false,
  loading: false,
  block: false,
});

Enter fullscreen mode Exit fullscreen mode

3.2 Variant System: variant + color

Common button types include: primary, secondary, outline, ghost. Inspired by Nuxt UI v4’s variant + color design, I chose to completely decouple “visual mode” from “semantic color”.

type Variant = "filled" | "outline";
type Color = "primary" | "success" | "warning" | "error";

Enter fullscreen mode Exit fullscreen mode

Why keep only filled and outline, removing ghost?

Variant Usage Frequency Keep? filled 🔥🔥🔥🔥🔥 Extremely high ✅ Keep outline 🔥🔥🔥🔥 High ✅ Keep ghost 🔥 Low ❌ Removed (can be replaced by outline)

Similarly, keep only 4 colors:

Color Usage Frequency Keep? primary 🔥🔥🔥🔥🔥 Extremely high ✅ Keep success 🔥🔥🔥 Medium ✅ Keep warning 🔥 Low ✅ Keep error 🔥🔥 Medium ✅ Keep neutral 🔥 Low ❌ Removed (can be replaced by outline)

3.3 Size Design

type Size = "sm" | "md" | "lg";

Enter fullscreen mode Exit fullscreen mode

Compared with Nuxt UI v4’s five sizes (xs, sm, md, lg, xl), I made a simplification. I removed xs and xl because the smallest use cases can be covered by Badge or other non-button components, and I rarely encounter extra-large buttons in a personal blog context.

Default size selection: Mainstream UI libraries (Naive UI, PrimeVue, etc.) have default button heights around 32-34px, which corresponds to our sm, so the default size is sm.

const props = withDefaults(defineProps<Props>(), {
  size: "sm", // default small
});

Enter fullscreen mode Exit fullscreen mode

3.4 Icon Design: Only Use Slots

To keep things minimalist, the Button component does not provide an icon prop, only the #icon slot. When users need an icon, they simply put content in the slot:

<Button>
  <template #icon>🔍</template>
  Search
</Button>

Enter fullscreen mode Exit fullscreen mode

Although this requires a few more characters, it avoids confusion between prop and slot priority, and better follows the single responsibility principle. Also, the slot can accept any content (strings, emojis, icon components), with complete flexibility.

Design consideration: Nuxt UI v4 provides an icon prop and multiple icon-related attributes (leading-icon/trailing-icon). But in a personal blog context, the vast majority of icon buttons are simply “icon + text”, and using a slot is sufficient for all use cases, reducing learning and maintenance costs.

IV. Slot Design: Default Slot vs label Prop

To support both quick writing and custom content, provide both label prop and default slot:

<span class="mg-button-label">
  <slot>{{ label }}</slot>
</span>

Enter fullscreen mode Exit fullscreen mode

• If default slot content is provided, display it
• Otherwise, display the label prop

Both usage styles are supported:

<!-- Using label prop -->
<Button label="Submit" />

<!-- Using default slot -->
<Button>Submit</Button>

Enter fullscreen mode Exit fullscreen mode

V. State Handling

5.1 Disabled State

Both disabled and loading disable the button:

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

Enter fullscreen mode Exit fullscreen mode

<button :disabled="isDisabled">

Enter fullscreen mode Exit fullscreen mode

5.2 Loading State

Show a spinning animation when loading, hide icon and text:

<template v-if="loading">
  <span class="mg-button-loading-icon" />
</template>
<template v-else>
  <span v-if="hasIconSlot" class="mg-button-icon">
    <slot name="icon" />
  </span>
  <span v-if="hasLabel" class="mg-button-label">
    <slot>{{ label }}</slot>
  </span>
</template>

Enter fullscreen mode Exit fullscreen mode

Pure CSS loading animation:

.mg-button-loading-icon {
  width: 1rem;
  height: 1rem;
  border: 2px solid currentColor;
  border-top-color: transparent;
  border-radius: 50%;
  animation: mg-button-spin 0.6s linear infinite;
}
@keyframes mg-button-spin {
  to {
    transform: rotate(360deg);
  }
}

Enter fullscreen mode Exit fullscreen mode

VI. CSS Styling

6.1 Base Styles

Buttons use inline-flex layout, content centered both horizontally and vertically, with straight corners (--ui-radius-none), padding and font size using design tokens.

.mg-button {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: var(--ui-spacing-sm);
  font-weight: 500;
  transition: all var(--ui-motion-duration-neural) ease;
  cursor: pointer;
  border-radius: var(--ui-radius-none);
  border: none;
  background: transparent;
  white-space: nowrap;
  padding: var(--ui-spacing-sm) var(--ui-spacing-md);
  font-size: var(--ui-typography-size-body);
}

Enter fullscreen mode Exit fullscreen mode

6.2 Size Variants

Size Padding Font Size sm sm / md --ui-typography-size-code (13px) md md / lg --ui-typography-size-body (15px) lg lg / xl 1.125rem (18px)

.mg-button-sm {
  padding: var(--ui-spacing-sm) var(--ui-spacing-md);
  font-size: var(--ui-typography-size-code);
}
.mg-button-md {
  padding: var(--ui-spacing-md) var(--ui-spacing-lg);
  font-size: var(--ui-typography-size-body);
}
.mg-button-lg {
  padding: var(--ui-spacing-lg) var(--ui-spacing-xl);
  font-size: 1.125rem;
}

Enter fullscreen mode Exit fullscreen mode

6.3 Block Button

.mg-button-block {
  width: 100%;
}

Enter fullscreen mode Exit fullscreen mode

6.4 Icon and Label Containers

The icon container uses inline-flex with line-height: 0 to eliminate line-height influence. SVG or iconify icons inside are forced to block display with width/height set to 1em.

.mg-button-icon {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  flex-shrink: 0;
  line-height: 0;
}
.mg-button-icon svg,
.mg-button-icon .iconify {
  display: block;
  width: 1em;
  height: 1em;
}
.mg-button-label {
  display: inline-flex;
  align-items: center;
}

Enter fullscreen mode Exit fullscreen mode

6.5 Solving Icon-Only Button Centering

When a button has only an icon and no text, the empty .mg-button-label occupies space and breaks centering. Hide empty labels with the :empty pseudo-class:

.mg-button-label:empty {
  display: none;
}

Enter fullscreen mode Exit fullscreen mode

Also check for real content before rendering the label:

const hasLabel = computed(() => !!props.label || !!slots.default);

Enter fullscreen mode Exit fullscreen mode

<span v-if="hasLabel" class="mg-button-label">
  <slot>{{ label }}</slot>
</span>

Enter fullscreen mode Exit fullscreen mode

6.6 Variant Styles

filled and outline variants correspond to filled background and transparent background with border, respectively. Colors are dynamically combined via the color prop. For example, .mg-button-filled-primary uses --ui-primary as background color.

VII. Accessibility

Add ARIA attributes to improve accessibility:

<button
  :aria-busy="loading"
  :aria-disabled="disabled || loading"
>

Enter fullscreen mode Exit fullscreen mode

Screen readers can correctly read the button’s loading and disabled states.

VIII. Attribute Inheritance

Use v-bind="$attrs" to pass through native attributes:

<button v-bind="$attrs">

Enter fullscreen mode Exit fullscreen mode

Users can directly pass attributes like id, name, data-*, aria-*:

<Button id="submit-btn" name="submit" data-testid="submit">
  Submit
</Button>

Enter fullscreen mode Exit fullscreen mode

IX. Final Code

<template>
  <button
    v-bind="$attrs"
    class="mg-button"
    :class="[
      `mg-button-${variant}-${color}`,
      `mg-button-${size}`,
      { 'mg-button-block': block, 'mg-button-loading': loading },
    ]"
    :disabled="disabled || loading"
    :aria-busy="loading"
    :aria-disabled="disabled || loading"
    @click="handleClick"
  >
    <template v-if="loading">
      <span class="mg-button-loading-icon" />
    </template>

    <template v-else>
      <span v-if="hasIconSlot" class="mg-button-icon">
        <slot name="icon" />
      </span>
      <span v-if="hasLabel" class="mg-button-label">
        <slot>{{ label }}</slot>
      </span>
    </template>
  </button>
</template>

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

const slots = useSlots();
const hasIconSlot = computed(() => !!slots.icon);
const hasLabel = computed(() => !!props.label || !!slots.default);

type Variant = "filled" | "outline";
type Color = "primary" | "success" | "warning" | "error";
type Size = "sm" | "md" | "lg";

interface Props {
  label?: string;
  variant?: Variant;
  color?: Color;
  size?: Size;
  disabled?: boolean;
  loading?: boolean;
  block?: boolean;
}

const props = withDefaults(defineProps<Props>(), {
  label: "",
  variant: "filled",
  color: "primary",
  size: "sm",
  disabled: false,
  loading: false,
  block: false,
});

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

const handleClick = (event: MouseEvent) => {
  if (props.disabled || props.loading) return;
  emit("click", event);
};
</script>

Enter fullscreen mode Exit fullscreen mode

X. Comparison with Mainstream UI Libraries

API Feature Moongate UI Nuxt UI v4 Naive UI (NButton) PrimeVue (Button) Core style variant (filled/outline) variant + color type severity + variant Size size (sm/md/lg) size (xs/sm/md/lg/xl) size (small/medium/large) size (small/medium/large) Disabled disabled disabled disabled disabled Loading loading loading / loadingAuto loading loading Block block block block fluid Icon #icon slot icon / leading-icon / trailing-icon + slot None icon + iconPos Extra styles None square dashed, circle, round rounded, raised, outlined

The comparison clearly shows:

• Decoupling variant and color: variant focuses on “visual mode”, color focuses on “semantic meaning”
• Streamlined sizing: 3 sizes are sufficient for personal blog scenarios
• Icon flexibility: The #icon slot achieves the same effect as props, with more flexibility
• Semantic naming: Using filled and outline more accurately describes the visual style

XI. Additional Detail: The Width Change Trap in Loading State

There’s a common but easily overlooked issue when using the loading attribute — “button width changes when loading”. When the loading animation (e.g., a spinner) appears, it changes the button’s internal children, usually causing the container to widen and layout shifts. This is essentially Cumulative Layout Shift (CLS).

An elegant solution: reserve space with min-width, and absolutely position the loading icon so it doesn’t affect layout.

.mg-button {
  /* 1. Reserve enough space to ensure consistent width in loading and normal states */
  min-width: 88px;
}

.mg-button-loading .mg-button-label {
  opacity: 0;
}

.mg-button-loading-icon {
  /* 2. Absolutely position the loading icon centered, without affecting layout */
  position: absolute;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
}

Enter fullscreen mode Exit fullscreen mode

XII. Design Decision Summary

Decision Reason Remove xs size Low usage frequency, simplify API Remove ghost variant Can be replaced by outline Remove neutral color Can be replaced by outline + default color Default size sm Mainstream UI libraries default to ~32px Only use #icon slot Avoid prop/slot confusion, keep it simple label prop + default slot Support both writing styles Hide empty label Solve icon-only button centering v-bind="$attrs" Pass through native attributes, maintain flexibility min-width + absolute positioned loading icon Prevent layout shift during loading

© 2026 yuelinghuashu. This work is licensed under CC BY-NC 4.0.