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

Source: Dev.to

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

🔍 Search

Submitting

Full Width Button

Small

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

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(), { label: "", disabled: false, loading: false, block: false, });

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?

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)

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(), { size: “sm”, // default small });

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:

🔍 Search

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. To support both quick writing and custom content, provide both label prop and default slot:

{{ label }}

If default slot content is provided, display it Otherwise, display the label prop Both usage styles are supported:

Submit

Both disabled and loading disable the button: const isDisabled = computed(() => props.disabled || props.loading);

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

{{ label }}

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

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

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

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

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

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

{{ label }}

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. Add ARIA attributes to improve accessibility:

Screen readers can correctly read the button’s loading and disabled states. Use v-bind=“$attrs” to pass through native attributes:

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

Submit

    {{ label }}
  

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(), { label: "", variant: “filled”, color: “primary”, size: “sm”, disabled: false, loading: false, block: false, });

const emit = defineEmits();

const handleClick = (event: MouseEvent) => { if (props.disabled || props.loading) return; emit(“click”, event); };

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

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

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.