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>

After analysis, the Button component needs to support:

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

}

Default value design:

const props = withDefaults(defineProps<Props>(), {

  label: "",

  disabled: false,

  loading: false,

  block: false,

});

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";

Why keep only filled and outline, removing ghost?

Similarly, keep only 4 colors:

3.3 Size Design

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

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

});

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>

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>

• 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>

V. State Handling

5.1 Disabled State

Both disabled and loading disable the button:

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

<button :disabled="isDisabled">

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>

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);

  }

}

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);

}

6.2 Size Variants

.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;

}

6.3 Block Button

.mg-button-block {

  width: 100%;

}

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;

}

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;

}

Also check for real content before rendering the label:

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

<span v-if="hasLabel" class="mg-button-label">

  <slot>{{ label }}</slot>

</span>

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"

>

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">

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

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

  Submit

</Button>

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>

X. Comparison with Mainstream UI Libraries

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%);

}

XII. Design Decision Summary

The original Chinese version is available on my blog: moongate.top.


Try the component library on npm: moongate-vue


Explore the component documentation: vue.moongate.top

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