feat: Add consistent variant prop for design variant of buttons / chips

CHANGELOG.md

@@ -5,6 +5,21 @@
 
 # Changelog
 
+## UNRELEASED
+
+### 📝 Notes
+#### `NcButton` color variant and native type
+`NcButton` (and `NcDialogButton`) now provides a `variant` prop to set the color variant to use (e.g. `'primary'`) and allows to set the native button type using the `type` prop.
+The legacy behavior, `type` for the color variant and `nativeType` for the button type, still works but will be removed in the next major version.
+
+To make a later migration to version 9 easier you can already migrate your `NcButton` usage like this:
+```vue
+<!-- Before: -->
+<NcButton type="primary" native-type="submit">Submit</NcButton>
+<!-- After: -->
+<NcButton type="submit" variant="primary">Submit</NcButton>
+```
+
 ## [v8.23.1](https://github.com/nextcloud-libraries/nextcloud-vue/tree/v8.23.1) (2025-02-13)
 [Full Changelog](https://github.com/nextcloud-libraries/nextcloud-vue/compare/v8.23.0...v8.23.1)
 

src/components/NcActions/NcActions.vue

@@ -444,12 +444,12 @@
 </script>
 ```
 
-### Type variants
+### Design variants
 
 ```vue
 <template>
 	<div>
-		<NcActions :type="current">
+		<NcActions :variant="current">
 			<template #icon>
 				<SelectColor :size="20" />
 			</template>
@@ -461,7 +461,7 @@
 				Remove
 			</NcActionButton>
 
-			<NcActionButton v-for="row in types" close-after-click @click="define(row)" :key="`type-icon--${row}`">
+			<NcActionButton v-for="row in variants" close-after-click @click="define(row)" :key="`type-icon--${row}`">
 				<template #icon>
 					<CheckboxMarkedCircleOutline v-if="row === current" :size="20" />
 					<SelectColor v-else :size="20" />
@@ -470,15 +470,15 @@
 			</NcActionButton>
 		</NcActions>
 
-		<NcActions :type="current" menu-name="Choose a type">
+		<NcActions :variant="current" menu-name="Choose a variant">
 			<NcActionButton v-if="current" close-after-click @click="define()">
 				<template #icon>
 					<Delete :size="20" />
 				</template>
 				Remove
 			</NcActionButton>
 
-			<NcActionButton v-for="row in types" close-after-click @click="define(row)" :key="`type-text--${row}`">
+			<NcActionButton v-for="row in variants" close-after-click @click="define(row)" :key="`type-text--${row}`">
 				<template #icon>
 					<CheckboxMarkedCircleOutline v-if="row === current" :size="20" />
 					<SelectColor v-else :size="20" />
@@ -487,7 +487,7 @@
 			</NcActionButton>
 		</NcActions>
 
-		<NcActions :type="current"  menu-name="Choose a type">
+		<NcActions :variant="current"  menu-name="Choose a variant">
 			<template #icon>
 				<SelectColor :size="20" />
 			</template>
@@ -499,7 +499,7 @@
 				Remove
 			</NcActionButton>
 
-			<NcActionButton v-for="row in types" close-after-click @click="define(row)" :key="`type-icon-text--${row}`">
+			<NcActionButton v-for="row in variants" close-after-click @click="define(row)" :key="`type-icon-text--${row}`">
 				<template #icon>
 					<CheckboxMarkedCircleOutline v-if="row === current" :size="20" />
 					<SelectColor v-else :size="20" />
@@ -526,7 +526,7 @@
 	data() {
 		return {
 			current: 'primary',
-			types: [
+			variants: [
 				'primary',
 				'secondary',
 				'tertiary',
@@ -554,7 +554,7 @@
 		<p>Has buttons, button groups, links and router links, separators, texts. May have checkboxes and radio buttons. Separator can be used to make groups of radio buttons as well.</p>
 		<p><kbd>Arrows</kbd> are used to navigate between items, <kbd>Tab</kbd> is used to navigate to the next UI element on the page.</p>
 		<p>
-			<NcActions aria-label="Email menu" type="tertiary">
+			<NcActions aria-label="Email menu" variant="tertiary">
 				<NcActionButtonGroup>
 					<NcActionButton>
 						<template #icon>
@@ -606,11 +606,11 @@
 			</NcActions>
 		</p>
 		<p>
-			<NcActions aria-label="Text settings" type="tertiary">
+			<NcActions aria-label="Text settings" variant="tertiary">
 				<template #icon>
 					<FormatTitle :size="20" />
 				</template>
-				<NcActionButtonGroup name="Allignment">
+				<NcActionButtonGroup name="Alignment">
 					<NcActionButton aria-label="Left">
 						<template #icon>
 							<FormatAlignLeft :size="20" />
@@ -658,7 +658,7 @@
 		<p>Has links or router links. May use text elements, captions and separators.</p>
 		<p>Uses classic <kbd>Tab</kbd> navigation.</p>
 		<p>
-			<NcActions aria-label="Applications navigation" :inline="2" type="tertiary">
+			<NcActions aria-label="Applications navigation" :inline="2" variant="tertiary">
 				<NcActionLink href="/apps/dashboard" icon="icon-category-dashboard-white">
 					Dashboard
 				</NcActionLink>
@@ -696,7 +696,7 @@
 			</NcActions>
 		</p>
 
-		<h2>Toolip</h2>
+		<h2>Tooltip</h2>
 		<p>Has only text and no interactive elements.</p>
 		<p>
 			<NcActions aria-label="Contact" :inline="1">
@@ -726,7 +726,7 @@
 import OpenInNewIcon from 'vue-material-design-icons/OpenInNew.vue'
 import DownloadIcon from 'vue-material-design-icons/Download.vue'
 
-// Formating icons
+// Formatting icons
 import FormatTitle from 'vue-material-design-icons/FormatTitle.vue'
 import FormatAlignLeft from 'vue-material-design-icons/FormatAlignLeft.vue'
 import FormatAlignCenter from 'vue-material-design-icons/FormatAlignCenter.vue'
@@ -751,7 +751,7 @@
 		OpenInNewIcon,
 		DownloadIcon,
 
-		// Formating icons
+		// Formatting icons
 		FormatTitle,
 		FormatAlignLeft,
 		FormatAlignCenter,
@@ -764,7 +764,7 @@
 	data() {
 		return {
 			selected: false,
-			// Formating
+			// Formatting
 			checked: {
 				bold: true,
 				italic: false,
@@ -965,7 +965,7 @@
 /**
  * The Actions component can be used to display one ore more actions.
  * If only a single action is provided, it will be rendered as an inline icon.
- * For more, a menu indicator will be shown and a popovermenu containing the
+ * For more, a menu indicator will be shown and a popover menu containing the
  * actions will be opened on click.
  *
  * @since 0.10.0
@@ -1074,14 +1074,16 @@
 		},
 
 		/**
-		 * Specifies the button type used for trigger and single actions buttons
+		 * Specifies the button variant used for trigger and single actions buttons.
+		 *
 		 * Accepted values: primary, secondary, tertiary, tertiary-no-background, tertiary-on-primary, error, warning, success. If left empty,
 		 * the default button style will be applied.
+		 * @deprecated use `variant` instead - will be removed with v9
 		 */
 		type: {
 			type: String,
 			validator(value) {
-				return ['primary', 'secondary', 'tertiary', 'tertiary-no-background', 'tertiary-on-primary', 'error', 'warning', 'success'].indexOf(value) !== -1
+				return ['primary', 'secondary', 'tertiary', 'tertiary-no-background', 'tertiary-on-primary', 'error', 'warning', 'success'].includes(value)
 			},
 			default: null,
 		},
@@ -1158,6 +1160,22 @@
 			type: Number,
 			default: 0,
 		},
+
+		/**
+		 * Specifies the button variant used for trigger and single actions buttons.
+		 *
+		 * Accepted values: primary, secondary, tertiary, tertiary-no-background, tertiary-on-primary, error, warning, success.
+		 * If left empty, the default button style will be applied.
+		 *
+		 * @since 8.23.0
+		 */
+		variant: {
+			type: String,
+			validator(value) {
+				return ['primary', 'secondary', 'tertiary', 'tertiary-no-background', 'tertiary-on-primary', 'error', 'warning', 'success'].includes(value)
+			},
+			default: null,
+		},
 	},
 
 	emits: [
@@ -1216,9 +1234,9 @@
 	},
 
 	computed: {
-		triggerBtnType() {
+		triggerButtonVariant() {
 			// If requested, we use a primary button
-			return this.type || (this.primary
+			return (this.type ?? this.variant) || (this.primary
 				? 'primary'
 				// If it has a name, we use a secondary button
 				: this.menuName ? 'secondary' : 'tertiary')
@@ -1498,7 +1516,7 @@
 			return this.$refs.menu.querySelector('li.active')
 		},
 		/**
 		 * @return {NodeListOf<HTMLElement>}
 		 */
 		getFocusableMenuItemElements() {
 			return this.$refs.menu.querySelectorAll(focusableSelector)
@@ -1660,7 +1678,7 @@
 			this.$emit('blur', event)
 
 			// When there is no focusable elements to handle Tab press from actions menu
-			// It requries manual closing
+			// It requires manual closing
 			if (this.actionsMenuSemanticType === 'tooltip') {
 				// Tooltip is supposed to have no focusable element.
 				// However, if there is a custom focusable element, it will be auto-focused and cause the menu to be closed on open.
@@ -1808,12 +1826,12 @@
 					},
 					ref: action?.data?.ref,
 					props: {
-						// If it has a menuName, we use a secondary button
-						type: this.type || (buttonText ? 'secondary' : 'tertiary'),
+						...propsToForward,
 						disabled: this.disabled || action?.componentOptions?.propsData?.disabled,
 						pressed: action?.componentOptions?.propsData?.modelValue,
-						nativeType,
-						...propsToForward,
+						type: nativeType,
+						// If it has a menuName, we use a secondary button
+						variant: (this.type ?? this.variant) || (buttonText ? 'secondary' : 'tertiary'),
 					},
 					on: {
 						focus: this.onFocus,
@@ -1892,7 +1910,7 @@
 					h('NcButton', {
 						class: 'action-item__menutoggle',
 						props: {
-							type: this.triggerBtnType,
+							variant: this.triggerButtonVariant,
 							disabled: this.disabled,
 						},
 						slot: 'trigger',
@@ -1968,7 +1986,7 @@
 				{
 					class: [
 						'action-items',
-						`action-item--${this.triggerBtnType}`,
+						`action-item--${this.triggerButtonVariant}`,
 					],
 				},
 				[
@@ -1999,7 +2017,7 @@
 			{
 				class: [
 					'action-item action-item--default-popover',
-					`action-item--${this.triggerBtnType}`,
+					`action-item--${this.triggerButtonVariant}`,
 					{
 						'action-item--open': this.opened,
 					},

src/components/NcAppContent/NcAppDetailsToggle.vue

@@ -5,10 +5,10 @@
 
 <template>
 	<NcButton v-tooltip="title"
-		type="tertiary"
-		:aria-label="title"
 		class="app-details-toggle"
-		:class="{ 'app-details-toggle--mobile': isMobile }">
+		:class="{ 'app-details-toggle--mobile': isMobile }"
+		:aria-label="title"
+		variant="tertiary">
 		<template #icon>
 			<ArrowLeft v-if="isRtl" :size="20" />
 			<ArrowRight v-else :size="20" />

src/components/NcAppNavigationItem/NcAppNavigationIconCollapsible.vue

@@ -7,8 +7,8 @@
 	<!-- Button to expand or collapse children -->
 	<NcButton class="icon-collapse"
 		:class="{'icon-collapse--open':open}"
-		type="tertiary"
 		:aria-label="labelButton"
+		variant="tertiary"
 		@click="onClick">
 		<template #icon>
 			<ChevronUp v-if="open"

src/components/NcAppNavigationItem/NcInputConfirmCancel.vue

@@ -21,18 +21,18 @@
 				class="app-navigation-input-confirm__input"
 				:placeholder="placeholder">
 
-			<NcButton native-type="submit"
-				type="primary"
-				:aria-label="labelConfirm"
+			<NcButton :aria-label="labelConfirm"
+				type="submit"
+				variant="primary"
 				@click.stop.prevent="confirm">
 				<template #icon>
 					<ArrowRight :size="20" />
 				</template>
 			</NcButton>
 
-			<NcButton native-type="reset"
-				:type="primary ? 'primary' : 'tertiary'"
-				:aria-label="labelCancel"
+			<NcButton :aria-label="labelCancel"
+				type="reset"
+				:variant="primary ? 'primary' : 'tertiary'"
 				@click.stop.prevent="cancel">
 				<template #icon>
 					<Close :size="20" />
@@ -42,11 +42,11 @@
 	</div>
 </template>
 <script>
-import NcButton from '../NcButton/index.js'
 import { t } from '../../l10n.js'
 
 import ArrowRight from 'vue-material-design-icons/ArrowRight.vue'
 import Close from 'vue-material-design-icons/Close.vue'
+import NcButton from '../NcButton/index.js'
 
 export default {
 	name: 'NcInputConfirmCancel',

src/components/NcAppNavigationNew/NcAppNavigationNew.vue

@@ -30,7 +30,7 @@
 	<div class="app-navigation-new">
 		<NcButton :id="buttonId"
 			:disabled="disabled"
-			:type="type"
+			:variant="type !== 'primary' ? type : variant"
 			@click="$emit('click')">
 			<template #icon>
 				<slot name="icon" />
@@ -62,13 +62,29 @@
 			type: String,
 			required: true,
 		},
+
+		/**
+		 * @deprecated use `variant` instead - will be removed with v9
+		 */
 		type: {
 			type: String,
 			default: 'primary',
 			validator(value) {
 				return ['primary', 'secondary', 'tertiary'].indexOf(value) !== -1
 			},
 		},
+
+		/**
+		 * The color variant to use.
+		 * @default 'primary'
+		 */
+		variant: {
+			type: String,
+			default: 'primary',
+			validator(value) {
+				return ['primary', 'secondary', 'tertiary'].indexOf(value) !== -1
+			},
+		}
 	},
 
 	emits: ['click'],

src/components/NcAppNavigationSearch/NcAppNavigationSearch.vue

@@ -31,7 +31,7 @@
 									Filter by year
 								</NcActionButton>
 							</NcActions>
-							<NcButton aria-label="Search globally" type="tertiary">
+							<NcButton aria-label="Search globally" variant="tertiary">
 								<template #icon>
 									<IconSearchGlobal :size="20" />
 								</template>