From 78b5984d49d8f17e8737751d5704e213726e196d Mon Sep 17 00:00:00 2001
From: Duncan McClean <duncan@duncanmcclean.com>
Date: Thu, 23 Jul 2026 15:31:55 +0100
Subject: [PATCH 1/5] extract `StarRating` into a ui component

---
 packages/cms/src/ui.js                        |   1 +
 resources/css/cp.css                          |   1 -
 resources/js/bootstrap/cms/ui.js              |   1 +
 .../fieldtypes/StarRatingFieldtype.vue        |  68 ++----
 .../components/ui/StarRating/StarRating.vue}  | 106 ++++++++-
 resources/js/components/ui/index.js           |   1 +
 resources/js/stories/StarRating.stories.ts    | 220 ++++++++++++++++++
 resources/js/stories/docs/StarRating.mdx      |  27 +++
 resources/js/tests/Package.test.js            |   1 +
 9 files changed, 370 insertions(+), 56 deletions(-)
 rename resources/{css/components/fieldtypes/star-rating.css => js/components/ui/StarRating/StarRating.vue} (60%)
 create mode 100644 resources/js/stories/StarRating.stories.ts
 create mode 100644 resources/js/stories/docs/StarRating.mdx

diff --git a/packages/cms/src/ui.js b/packages/cms/src/ui.js
index 3f5150061c9..1e5f8bdc30a 100644
--- a/packages/cms/src/ui.js
+++ b/packages/cms/src/ui.js
@@ -98,6 +98,7 @@ export const {
     SplitterGroup,
     SplitterPanel,
     SplitterResizeHandle,
+    StarRating,
     StatusIndicator,
     Subheading,
     Switch,
diff --git a/resources/css/cp.css b/resources/css/cp.css
index d3aef6130c6..9f8c9786f8f 100644
--- a/resources/css/cp.css
+++ b/resources/css/cp.css
@@ -38,6 +38,5 @@
 @import './components/fieldtypes/partial.css';
 @import './components/fieldtypes/relationship.css';
 @import './components/fieldtypes/section.css';
-@import './components/fieldtypes/star-rating.css';
 @import './components/fieldtypes/table.css';
 @import './components/fieldtypes/width.css';
diff --git a/resources/js/bootstrap/cms/ui.js b/resources/js/bootstrap/cms/ui.js
index 68653dd3746..bc5209dea47 100644
--- a/resources/js/bootstrap/cms/ui.js
+++ b/resources/js/bootstrap/cms/ui.js
@@ -96,6 +96,7 @@ export {
     SplitterGroup,
     SplitterPanel,
     SplitterResizeHandle,
+    StarRating,
     StatusIndicator,
     Subheading,
     Switch,
diff --git a/resources/js/components/fieldtypes/StarRatingFieldtype.vue b/resources/js/components/fieldtypes/StarRatingFieldtype.vue
index c863da83eb7..a42949f91a9 100644
--- a/resources/js/components/fieldtypes/StarRatingFieldtype.vue
+++ b/resources/js/components/fieldtypes/StarRatingFieldtype.vue
@@ -1,68 +1,30 @@
 <script setup>
 import Fieldtype from '@/components/fieldtypes/fieldtype.js';
+import { StarRating } from '@/components/ui';
 import { __ } from '@/bootstrap/globals';
-import { computed, ref } from 'vue';
+import { computed } from 'vue';
 
 const emit = defineEmits(Fieldtype.emits);
 const props = defineProps(Fieldtype.props);
 const { expose, update, isReadOnly, name } = Fieldtype.use(emit, props);
 defineExpose(expose);
 
-// Hide fill until the user interacts; value still sits at min for correct thumb alignment.
-const hasInteracted = ref(Boolean(props.value));
-
 const step = computed(() => props.config.step ?? 1);
-const min = computed(() => props.config.min ?? step.value);
-const maxStars = computed(() => props.config.max_stars ?? 5);
-const isDisabled = computed(() => props.config.disabled || isReadOnly.value);
-const ariaLabel = computed(() => __(props.config.display ?? 'Star rating'));
-const isUnrated = computed(() => ! props.value && ! hasInteracted.value);
-
-function onKeydown(event) {
-    const navigationKeys = ['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End'];
-    if (! navigationKeys.includes(event.key)) return;
-
-    if (isUnrated.value) {
-        if (event.key === 'End') {
-            // Reveal fill but let the browser jump to max.
-            hasInteracted.value = true;
-
-            return;
-        }
-
-        // Thumb is already at min — stop the browser jumping to min + step.
-        event.preventDefault();
-        hasInteracted.value = true;
-        update(min.value);
-
-        return;
-    }
+const label = computed(() => (props.config.display ? __(props.config.display) : null));
 
-    hasInteracted.value = true;
-}
+// Submissions made through a front-end form come back as strings.
+const rating = computed(() => (props.value === null || props.value === undefined || props.value === '' ? null : Number(props.value)));
 </script>
 
 <template>
-    <div class="show-focus-within w-fit rounded-xs ps-1.25 -ms-1.25" style="--focus-outline-offset: 0.1rem">
-        <input
-            type="range"
-            class="star-rating-input show-focus-within_target focus-visible:outline-hidden"
-            :class="{ 'star-rating-input--unrated': !value && !hasInteracted }"
-            data-star-rating
-            :name="name"
-            :min="min"
-            :max="maxStars"
-            :step="step"
-            :value="value || min"
-            :disabled="isDisabled"
-            :aria-label="ariaLabel"
-            :style="{
-                '--star-rating-max': maxStars,
-                '--star-rating-step': step,
-            }"
-            @keydown="onKeydown"
-            @pointerdown="hasInteracted = true"
-            @input="update(Number($event.target.value))"
-        />
-    </div>
+    <StarRating
+        :model-value="rating"
+        :name
+        :label
+        :min="config.min ?? step"
+        :max="config.max_stars ?? 5"
+        :step
+        :disabled="config.disabled || isReadOnly"
+        @update:model-value="update"
+    />
 </template>
diff --git a/resources/css/components/fieldtypes/star-rating.css b/resources/js/components/ui/StarRating/StarRating.vue
similarity index 60%
rename from resources/css/components/fieldtypes/star-rating.css
rename to resources/js/components/ui/StarRating/StarRating.vue
index a63b92450db..81a5095c365 100644
--- a/resources/css/components/fieldtypes/star-rating.css
+++ b/resources/js/components/ui/StarRating/StarRating.vue
@@ -1,6 +1,107 @@
+<script setup>
+import { computed, ref, useId } from 'vue';
+import { __ } from '@/bootstrap/globals';
+
+const props = defineProps({
+    /** Whether the rating is disabled. */
+    disabled: { type: Boolean, default: false },
+    /** ID attribute for the rating. */
+    id: { type: String, default: () => useId() },
+    /** Accessible label for the rating. */
+    label: { type: String, default: null },
+    /** The number of stars. */
+    max: { type: Number, default: 5 },
+    /** The lowest selectable rating. Defaults to a single step. */
+    min: { type: Number, default: null },
+    /** The controlled value of the rating. */
+    modelValue: { type: Number, default: null },
+    /** Name attribute for the rating. */
+    name: { type: String, default: null },
+    /** Controls the size of the stars. <br><br> Options: `sm`, `base`, `lg` */
+    size: {
+        type: String,
+        default: 'base',
+        validator: (value) => ['sm', 'base', 'lg'].includes(value),
+    },
+    /** The increment between ratings. Use `0.5` to allow half stars. */
+    step: { type: Number, default: 1 },
+});
+
+const emit = defineEmits(['update:modelValue']);
+
+// Hide the fill until the user interacts; the value still sits at min so the thumb stays aligned.
+const hasInteracted = ref(Boolean(props.modelValue));
+
+const starSizes = {
+    sm: '1.125rem',
+    base: '1.5rem',
+    lg: '2rem',
+};
+
+const min = computed(() => props.min ?? props.step);
+const isUnrated = computed(() => !props.modelValue && !hasInteracted.value);
+const ariaLabel = computed(() => props.label ?? __('Star rating'));
+
+function onKeydown(event) {
+    const navigationKeys = ['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End'];
+    if (!navigationKeys.includes(event.key)) return;
+
+    if (isUnrated.value) {
+        if (event.key === 'End') {
+            // Reveal the fill but let the browser jump to max.
+            hasInteracted.value = true;
+
+            return;
+        }
+
+        // The thumb is already at min — stop the browser jumping to min + step.
+        event.preventDefault();
+        hasInteracted.value = true;
+        emit('update:modelValue', min.value);
+
+        return;
+    }
+
+    hasInteracted.value = true;
+}
+</script>
+
+<template>
+    <div
+        class="w-fit rounded-xs ps-1.25 -ms-1.25 has-[:focus-visible]:focus-outline"
+        style="--focus-outline-offset: 0.1rem"
+        data-ui-star-rating
+    >
+        <input
+            type="range"
+            class="focus-visible:outline-hidden"
+            data-ui-control
+            data-ui-star-rating-input
+            :data-unrated="isUnrated ? '' : null"
+            :id
+            :name
+            :min="min"
+            :max
+            :step
+            :value="modelValue ?? min"
+            :disabled
+            :aria-label="ariaLabel"
+            :style="{
+                '--s': starSizes[size],
+                '--star-rating-max': max,
+                '--star-rating-step': step,
+            }"
+            @keydown="onKeydown"
+            @pointerdown="hasInteracted = true"
+            @input="emit('update:modelValue', Number($event.target.value))"
+        />
+    </div>
+</template>
+
+<style>
 /* CSS-only star rating via range input — https://css-tricks.com/a-css-only-star-rating-component-and-more-part-1/ */
 
-.star-rating-input {
+[data-ui-star-rating-input] {
     --s: 1.5rem;
     --star-rating-gap: 0.4rem;
     --star-rating-max: 5;
@@ -74,7 +175,7 @@
         border-image: conic-gradient(at calc(50% + var(--_fill-offset)), transparent 50%, var(--_fill) 0) fill 0 // var(--s) 500px;
     }
 
-    &.star-rating-input--unrated {
+    &[data-unrated] {
         &::-webkit-slider-thumb {
             border-image: conic-gradient(transparent 0) fill 0 // var(--s) 500px;
         }
@@ -98,3 +199,4 @@
         border: none;
     }
 }
+</style>
diff --git a/resources/js/components/ui/index.js b/resources/js/components/ui/index.js
index 9527d5461c8..2993bd64e44 100644
--- a/resources/js/components/ui/index.js
+++ b/resources/js/components/ui/index.js
@@ -68,6 +68,7 @@ export { default as Skeleton } from './Skeleton.vue';
 export { default as SplitterGroup } from './Splitter/Group.vue';
 export { default as SplitterPanel } from './Splitter/Panel.vue';
 export { default as SplitterResizeHandle } from './Splitter/ResizeHandle.vue';
+export { default as StarRating } from './StarRating/StarRating.vue';
 export { default as Subheading } from './Subheading.vue';
 export { default as Switch } from './Switch.vue';
 export { default as TabContent } from './Tabs/Content.vue';
diff --git a/resources/js/stories/StarRating.stories.ts b/resources/js/stories/StarRating.stories.ts
new file mode 100644
index 00000000000..1770fb83c98
--- /dev/null
+++ b/resources/js/stories/StarRating.stories.ts
@@ -0,0 +1,220 @@
+import type {Meta, StoryObj} from '@storybook/vue3';
+import {ref} from 'vue';
+import {expect, fn, userEvent, within} from 'storybook/test';
+import {Field, StarRating} from '@ui';
+
+const meta = {
+    title: 'Forms/StarRating',
+    component: StarRating,
+    argTypes: {
+        size: {
+            control: 'select',
+            options: ['sm', 'base', 'lg'],
+        },
+        'update:modelValue': {
+            description: 'Event handler called when the rating changes.',
+            table: {
+                category: 'events',
+                type: { summary: '(value: number) => void' }
+            }
+        }
+    },
+} satisfies Meta<typeof StarRating>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const defaultCode = `
+<StarRating v-model="rating" label="Rate your experience" />
+`;
+
+export const _DocsIntro: Story = {
+    tags: ['!dev'],
+    parameters: {
+        docs: {
+            source: { code: defaultCode }
+        }
+    },
+    render: () => ({
+        components: { StarRating },
+        setup() {
+            const rating = ref(null);
+            return { rating };
+        },
+        template: defaultCode,
+    }),
+};
+
+const halfStarsCode = `
+<div class="space-y-6">
+    <Field label="Whole stars">
+        <StarRating v-model="whole" />
+    </Field>
+    <Field label="Half stars">
+        <StarRating v-model="half" :step="0.5" />
+    </Field>
+</div>
+`;
+
+export const _HalfStars: Story = {
+    tags: ['!dev'],
+    parameters: {
+        docs: {
+            source: { code: halfStarsCode }
+        }
+    },
+    render: () => ({
+        components: { Field, StarRating },
+        setup() {
+            const whole = ref(3);
+            const half = ref(3.5);
+            return { whole, half };
+        },
+        template: halfStarsCode,
+    }),
+};
+
+const maxCode = `
+<div class="space-y-6">
+    <Field label="Out of three">
+        <StarRating v-model="three" :max="3" />
+    </Field>
+    <Field label="Out of ten">
+        <StarRating v-model="ten" :max="10" />
+    </Field>
+</div>
+`;
+
+export const _Max: Story = {
+    tags: ['!dev'],
+    parameters: {
+        docs: {
+            source: { code: maxCode }
+        }
+    },
+    render: () => ({
+        components: { Field, StarRating },
+        setup() {
+            const three = ref(2);
+            const ten = ref(7);
+            return { three, ten };
+        },
+        template: maxCode,
+    }),
+};
+
+const sizesCode = `
+<div class="space-y-6">
+    <Field label="Small"><StarRating v-model="small" size="sm" /></Field>
+    <Field label="Base"><StarRating v-model="base" /></Field>
+    <Field label="Large"><StarRating v-model="large" size="lg" /></Field>
+</div>
+`;
+
+export const _Sizes: Story = {
+    tags: ['!dev'],
+    parameters: {
+        docs: {
+            source: { code: sizesCode }
+        }
+    },
+    render: () => ({
+        components: { Field, StarRating },
+        setup() {
+            const small = ref(4);
+            const base = ref(4);
+            const large = ref(4);
+            return { small, base, large };
+        },
+        template: sizesCode,
+    }),
+};
+
+const disabledCode = `
+<StarRating :model-value="4" disabled />
+`;
+
+export const _Disabled: Story = {
+    tags: ['!dev'],
+    parameters: {
+        docs: {
+            source: { code: disabledCode }
+        }
+    },
+    render: () => ({
+        components: { StarRating },
+        template: disabledCode,
+    }),
+};
+
+export const TestStartsUnrated: Story = {
+    tags: ['!dev', 'test'],
+    render: () => ({
+        components: { StarRating },
+        template: `<StarRating label="Rating" />`,
+    }),
+    play: async ({ canvasElement }) => {
+        const input = within(canvasElement).getByRole('slider') as HTMLInputElement;
+
+        // The thumb sits at the minimum so it lines up with the first star, but nothing is filled in yet.
+        expect(input).toHaveAttribute('data-unrated');
+        expect(input.value).toBe('1');
+    },
+};
+
+export const TestArrowKeySelectsMinimum: Story = {
+    tags: ['!dev', 'test'],
+    args: {
+        'onUpdate:modelValue': fn(),
+    },
+    render: (args) => ({
+        components: { StarRating },
+        setup() {
+            return { onUpdate: args['onUpdate:modelValue'] };
+        },
+        template: `<StarRating label="Rating" @update:modelValue="onUpdate" />`,
+    }),
+    play: async ({ canvasElement, args }) => {
+        const input = within(canvasElement).getByRole('slider') as HTMLInputElement;
+
+        input.focus();
+        await userEvent.keyboard('{ArrowRight}');
+
+        // Without intervention the browser would jump straight to two stars.
+        expect(args['onUpdate:modelValue']).toHaveBeenCalledWith(1);
+        expect(input).not.toHaveAttribute('data-unrated');
+    },
+};
+
+export const TestPointerRevealsTheFill: Story = {
+    tags: ['!dev', 'test'],
+    render: () => ({
+        components: { StarRating },
+        template: `<StarRating label="Rating" />`,
+    }),
+    play: async ({ canvasElement }) => {
+        const input = within(canvasElement).getByRole('slider') as HTMLInputElement;
+
+        await userEvent.click(input);
+
+        expect(input).not.toHaveAttribute('data-unrated');
+    },
+};
+
+export const TestHalfStars: Story = {
+    tags: ['!dev', 'test'],
+    render: () => ({
+        components: { StarRating },
+        template: `<StarRating label="Rating" :model-value="3.5" :max="10" :step="0.5" />`,
+    }),
+    play: async ({ canvasElement }) => {
+        const input = within(canvasElement).getByRole('slider') as HTMLInputElement;
+
+        // The minimum falls back to a single step, so half stars can start at 0.5.
+        expect(input.min).toBe('0.5');
+        expect(input.max).toBe('10');
+        expect(input.step).toBe('0.5');
+        expect(input.value).toBe('3.5');
+        expect(input).not.toHaveAttribute('data-unrated');
+    },
+};
diff --git a/resources/js/stories/docs/StarRating.mdx b/resources/js/stories/docs/StarRating.mdx
new file mode 100644
index 00000000000..78e2f278328
--- /dev/null
+++ b/resources/js/stories/docs/StarRating.mdx
@@ -0,0 +1,27 @@
+import { Canvas, Meta, ArgTypes } from '@storybook/addon-docs/blocks';
+import * as StarRatingStories from '../StarRating.stories';
+
+<Meta of={StarRatingStories} />
+
+# StarRating
+A row of stars for collecting a rating. It's a native range input under the hood, so it's keyboard accessible.
+
+Nothing is filled in until the rating is set. The thumb still sits at the minimum so it lines up with the first star, but the fill stays hidden until the field is used or a value is provided.
+<Canvas of={StarRatingStories._DocsIntro} sourceState={'shown'} />
+
+## Half stars
+Set `step` to `0.5` to allow ratings like 3.5.
+<Canvas of={StarRatingStories._HalfStars} sourceState={'shown'} />
+
+## Number of stars
+Use `max` to change how many stars are shown.
+<Canvas of={StarRatingStories._Max} sourceState={'shown'} />
+
+## Sizes
+<Canvas of={StarRatingStories._Sizes} sourceState={'shown'} />
+
+## Disabled
+<Canvas of={StarRatingStories._Disabled} sourceState={'shown'} />
+
+## Arguments
+<ArgTypes of={StarRatingStories} />
diff --git a/resources/js/tests/Package.test.js b/resources/js/tests/Package.test.js
index 4da3ead2380..ec6295c2922 100644
--- a/resources/js/tests/Package.test.js
+++ b/resources/js/tests/Package.test.js
@@ -191,6 +191,7 @@ it('exports ui', async () => {
         'SplitterGroup',
         'SplitterPanel',
         'SplitterResizeHandle',
+        'StarRating',
         'Subheading',
         'Switch',
         'TabContent',

From 25cf7e4f7a286925c4ff5acafed324c130f3877a Mon Sep 17 00:00:00 2001
From: Duncan McClean <duncan@duncanmcclean.com>
Date: Thu, 23 Jul 2026 15:50:22 +0100
Subject: [PATCH 2/5] extract `RankList` into a ui component

---
 packages/cms/src/ui.js                        |   1 +
 resources/js/bootstrap/cms/ui.js              |   1 +
 .../fieldtypes/RankingFieldtype.vue           | 156 ++----------------
 .../js/components/ui/RankList/RankList.vue    | 146 ++++++++++++++++
 resources/js/components/ui/index.js           |   1 +
 resources/js/stories/RankList.stories.ts      | 155 +++++++++++++++++
 resources/js/stories/docs/RankList.mdx        |  21 +++
 resources/js/tests/Package.test.js            |   1 +
 8 files changed, 341 insertions(+), 141 deletions(-)
 create mode 100644 resources/js/components/ui/RankList/RankList.vue
 create mode 100644 resources/js/stories/RankList.stories.ts
 create mode 100644 resources/js/stories/docs/RankList.mdx

diff --git a/packages/cms/src/ui.js b/packages/cms/src/ui.js
index 1e5f8bdc30a..564b4568c4d 100644
--- a/packages/cms/src/ui.js
+++ b/packages/cms/src/ui.js
@@ -91,6 +91,7 @@ export const {
     PublishTabs,
     Radio,
     RadioGroup,
+    RankList,
     Select,
     Separator,
     Slider,
diff --git a/resources/js/bootstrap/cms/ui.js b/resources/js/bootstrap/cms/ui.js
index bc5209dea47..c311a2eb888 100644
--- a/resources/js/bootstrap/cms/ui.js
+++ b/resources/js/bootstrap/cms/ui.js
@@ -89,6 +89,7 @@ export {
     PublishTabs,
     Radio,
     RadioGroup,
+    RankList,
     Select,
     Separator,
     Slider,
diff --git a/resources/js/components/fieldtypes/RankingFieldtype.vue b/resources/js/components/fieldtypes/RankingFieldtype.vue
index a16e59f9858..479ef40898f 100644
--- a/resources/js/components/fieldtypes/RankingFieldtype.vue
+++ b/resources/js/components/fieldtypes/RankingFieldtype.vue
@@ -1,154 +1,28 @@
 <script setup>
 import Fieldtype from '@/components/fieldtypes/fieldtype.js';
-import { SortableList } from '@/components/sortable/Sortable.js';
-import { DragHandle } from '@/components/ui';
-import { computed, ref, watch } from 'vue';
+import { RankList } from '@/components/ui';
+import { __ } from '@/bootstrap/globals';
+import { computed } from 'vue';
 
 const emit = defineEmits(Fieldtype.emits);
 const props = defineProps(Fieldtype.props);
 const { expose, update, isReadOnly, name } = Fieldtype.use(emit, props);
 defineExpose(expose);
 
-const sortableItemClass = 'ranking-item';
-const sortableHandleClass = 'ranking-handle';
-
-const rankedValues = ref([]);
-
-const options = computed(() => {
-    const raw = props.config.options ?? {};
-    return Object.entries(raw).map(([value, label]) => ({ value, label: label || value }));
-});
-
-const isDisabled = computed(() => props.config.disabled || isReadOnly.value);
-
-const orderedRows = computed(() => rankedValues.value.map((value, index) => ({
-    value,
-    label: options.value.find((option) => option.value === value)?.label ?? value,
-    index,
-})));
-
-function defaultOrder() {
-    return options.value.map((option) => option.value);
-}
-
-function buildRankedValues(value) {
-    const order = Array.isArray(value) && value.length ? [...value] : defaultOrder();
-    const valid = new Set(options.value.map((option) => option.value));
-
-    const ranked = order.filter((item) => valid.has(item));
-
-    options.value.forEach((option) => {
-        if (! ranked.includes(option.value)) {
-            ranked.push(option.value);
-        }
-    });
-
-    return ranked;
-}
-
-const hasCustomOrder = computed(() => {
-    return JSON.stringify(rankedValues.value) !== JSON.stringify(defaultOrder());
-});
-
-function moveToRank(itemValue, event) {
-    const fromIndex = rankedValues.value.indexOf(itemValue);
-    const parsed = Number(event.target.value);
-
-    if (! isDisabled.value && fromIndex !== -1 && Number.isFinite(parsed)) {
-        const toIndex = Math.max(0, Math.min(rankedValues.value.length - 1, Math.round(parsed) - 1));
-
-        if (toIndex !== fromIndex) {
-            const next = [...rankedValues.value];
-            next.splice(fromIndex, 1);
-            next.splice(toIndex, 0, itemValue);
-            rankedValues.value = next;
-        }
-    }
-
-    // Reset the input to the item's canonical rank. When the requested rank is
-    // clamped to the item's current position, no reorder happens, so the binding
-    // wouldn't otherwise overwrite the invalid value left in the input.
-    event.target.value = rankedValues.value.indexOf(itemValue) + 1;
-}
-
-watch(
-    [() => props.value, options],
-    () => rankedValues.value = buildRankedValues(props.value),
-    { deep: true, immediate: true },
-);
-
-watch(
-    rankedValues,
-    (value) => {
-        const current = Array.isArray(props.value) ? props.value : [];
-
-        if (JSON.stringify(value) === JSON.stringify(current)) {
-            return;
-        }
-
-        update([...value]);
-    },
-    { deep: true },
+const options = computed(() =>
+    Object.entries(props.config.options ?? {}).map(([value, label]) => ({
+        value,
+        label: label ? __(label) : value,
+    })),
 );
 </script>
 
 <template>
-    <SortableList
-        v-if="orderedRows.length"
-        v-model="rankedValues"
-        :vertical="true"
-        :item-class="sortableItemClass"
-        :handle-class="sortableHandleClass"
-        :mirror="false"
-        :disabled="isDisabled"
-    >
-        <ul class="flex flex-col gap-2" role="list">
-            <li
-                v-for="row in orderedRows"
-                :key="row.value"
-                :class="sortableItemClass"
-                class="flex items-center gap-2 rounded-lg border border-gray-300 bg-white p-2 dark:border-gray-700 dark:bg-gray-900"
-            >
-                <DragHandle
-                    v-if="!isDisabled"
-                    :class="[
-                        sortableHandleClass,
-                        hasCustomOrder
-                            ? 'text-primary! [&_svg]:opacity-100'
-                            : '[&_svg]:opacity-75 dark:[&_svg]:opacity-50',
-                    ]"
-                    class="cursor-grab"
-                />
-                <input
-                    v-if="!isDisabled"
-                    type="number"
-                    class="size-6 shrink-0 rounded-md border border-gray-300 bg-white px-0 text-center text-xs font-semibold text-gray-800 shadow-ui-xs focus:focus-outline dark:border-gray-700 dark:bg-gray-925 dark:text-gray-200 [appearance:textfield] [&::-webkit-inner-spin-button]:appearance-none [&::-webkit-outer-spin-button]:appearance-none"
-                    :min="1"
-                    :max="orderedRows.length"
-                    step="1"
-                    :value="row.index + 1"
-                    :aria-label="`${__('Rank')} ${__(row.label)}`"
-                    @change="moveToRank(row.value, $event)"
-                >
-                <span
-                    v-else
-                    class="flex size-6 shrink-0 items-center justify-center rounded-md border border-gray-300 shadow-ui-xs bg-white text-xs font-semibold text-gray-800 dark:border-gray-700 dark:bg-gray-925 dark:text-gray-200"
-                    aria-hidden="true"
-                >
-                    {{ row.index + 1 }}
-                </span>
-                <span class="min-w-0 flex-1 text-sm text-gray-800 dark:text-gray-200">
-                    {{ __(row.label) }}
-                </span>
-                <input type="hidden" :name="`${name}[]`" :value="row.value">
-            </li>
-        </ul>
-    </SortableList>
+    <RankList
+        :model-value="value ?? []"
+        :options
+        :name
+        :disabled="config.disabled || isReadOnly"
+        @update:model-value="update"
+    />
 </template>
-
-<style scoped>
-.ranking-item.draggable-source--is-dragging {
-    /* Make the item slightly transparent than the default dragging opacity */
-    opacity: 0.65;
-}
-</style>
diff --git a/resources/js/components/ui/RankList/RankList.vue b/resources/js/components/ui/RankList/RankList.vue
new file mode 100644
index 00000000000..103e6fbf694
--- /dev/null
+++ b/resources/js/components/ui/RankList/RankList.vue
@@ -0,0 +1,146 @@
+<script setup>
+import { computed, ref, watch } from 'vue';
+import { SortableList } from '@/components/sortable/Sortable.js';
+import { __ } from '@/bootstrap/globals';
+import DragHandle from '../DragHandle.vue';
+
+const props = defineProps({
+    /** Whether the list can be reordered. */
+    disabled: { type: Boolean, default: false },
+    /** The controlled order, as an array of option values. */
+    modelValue: { type: Array, default: () => [] },
+    /** Name attribute for the hidden inputs holding the order. */
+    name: { type: String, default: null },
+    /** The items to rank. Each option supports `value` and `label`. */
+    options: { type: Array, default: () => [] },
+});
+
+const emit = defineEmits(['update:modelValue']);
+
+const sortableItemClass = 'rank-list-item';
+const sortableHandleClass = 'rank-list-handle';
+
+const ranked = ref([]);
+
+const defaultOrder = computed(() => props.options.map((option) => option.value));
+
+const rows = computed(() =>
+    ranked.value.map((value, index) => ({
+        value,
+        label: props.options.find((option) => option.value === value)?.label ?? value,
+        index,
+    })),
+);
+
+const hasCustomOrder = computed(() => JSON.stringify(ranked.value) !== JSON.stringify(defaultOrder.value));
+
+function reconcile(order) {
+    const values = new Set(defaultOrder.value);
+    const reconciled = (Array.isArray(order) && order.length ? order : defaultOrder.value).filter((value) =>
+        values.has(value),
+    );
+
+    defaultOrder.value.forEach((value) => {
+        if (!reconciled.includes(value)) {
+            reconciled.push(value);
+        }
+    });
+
+    return reconciled;
+}
+
+function moveToRank(value, event) {
+    const fromIndex = ranked.value.indexOf(value);
+    const requested = Number(event.target.value);
+
+    if (!props.disabled && fromIndex !== -1 && Number.isFinite(requested)) {
+        const toIndex = Math.max(0, Math.min(ranked.value.length - 1, Math.round(requested) - 1));
+
+        if (toIndex !== fromIndex) {
+            const next = [...ranked.value];
+            next.splice(fromIndex, 1);
+            next.splice(toIndex, 0, value);
+            ranked.value = next;
+        }
+    }
+
+    // Reset the input to the item's canonical rank. When the requested rank is
+    // clamped to the item's current position, no reorder happens, so the binding
+    // wouldn't otherwise overwrite the invalid value left in the input.
+    event.target.value = ranked.value.indexOf(value) + 1;
+}
+
+watch([() => props.modelValue, () => props.options], () => (ranked.value = reconcile(props.modelValue)), {
+    deep: true,
+    immediate: true,
+});
+
+watch(
+    ranked,
+    (value) => {
+        if (JSON.stringify(value) === JSON.stringify(props.modelValue)) return;
+
+        emit('update:modelValue', [...value]);
+    },
+    { deep: true },
+);
+</script>
+
+<template>
+    <SortableList
+        v-if="rows.length"
+        v-model="ranked"
+        :vertical="true"
+        :item-class="sortableItemClass"
+        :handle-class="sortableHandleClass"
+        :mirror="false"
+        :disabled="disabled"
+    >
+        <ul class="flex flex-col gap-2" role="list" data-ui-rank-list>
+            <li
+                v-for="row in rows"
+                :key="row.value"
+                :class="sortableItemClass"
+                class="flex items-center gap-2 rounded-lg border border-gray-300 bg-white p-2 dark:border-gray-700 dark:bg-gray-900"
+            >
+                <DragHandle
+                    v-if="!disabled"
+                    :class="[
+                        sortableHandleClass,
+                        hasCustomOrder ? 'text-primary! [&_svg]:opacity-100' : '[&_svg]:opacity-75 dark:[&_svg]:opacity-50',
+                    ]"
+                    class="cursor-grab"
+                />
+                <input
+                    v-if="!disabled"
+                    type="number"
+                    class="size-6 shrink-0 rounded-md border border-gray-300 bg-white px-0 text-center text-xs font-semibold text-gray-800 shadow-ui-xs focus:focus-outline dark:border-gray-700 dark:bg-gray-925 dark:text-gray-200 [appearance:textfield] [&::-webkit-inner-spin-button]:appearance-none [&::-webkit-outer-spin-button]:appearance-none"
+                    :min="1"
+                    :max="rows.length"
+                    step="1"
+                    :value="row.index + 1"
+                    :aria-label="`${__('Rank')} ${row.label}`"
+                    @change="moveToRank(row.value, $event)"
+                />
+                <span
+                    v-else
+                    class="flex size-6 shrink-0 items-center justify-center rounded-md border border-gray-300 bg-white text-xs font-semibold text-gray-800 shadow-ui-xs dark:border-gray-700 dark:bg-gray-925 dark:text-gray-200"
+                    aria-hidden="true"
+                >
+                    {{ row.index + 1 }}
+                </span>
+                <span class="min-w-0 flex-1 text-sm text-gray-800 dark:text-gray-200">
+                    {{ row.label }}
+                </span>
+                <input v-if="name" type="hidden" :name="`${name}[]`" :value="row.value" />
+            </li>
+        </ul>
+    </SortableList>
+</template>
+
+<style scoped>
+.rank-list-item.draggable-source--is-dragging {
+    /* Make the item slightly more transparent than the default dragging opacity */
+    opacity: 0.65;
+}
+</style>
diff --git a/resources/js/components/ui/index.js b/resources/js/components/ui/index.js
index 2993bd64e44..546d2349337 100644
--- a/resources/js/components/ui/index.js
+++ b/resources/js/components/ui/index.js
@@ -61,6 +61,7 @@ export { default as PanelHeader } from './Panel/Header.vue';
 export { default as Popover } from './Popover.vue';
 export { default as Radio } from './Radio/Item.vue';
 export { default as RadioGroup } from './Radio/Group.vue';
+export { default as RankList } from './RankList/RankList.vue';
 export { default as Select } from './Select/Select.vue';
 export { default as Separator } from './Separator.vue';
 export { default as Slider } from './Slider/Slider.vue';
diff --git a/resources/js/stories/RankList.stories.ts b/resources/js/stories/RankList.stories.ts
new file mode 100644
index 00000000000..0f81b116912
--- /dev/null
+++ b/resources/js/stories/RankList.stories.ts
@@ -0,0 +1,155 @@
+import type {Meta, StoryObj} from '@storybook/vue3';
+import {ref} from 'vue';
+import {expect, fn, userEvent, within} from 'storybook/test';
+import {Field, RankList} from '@ui';
+
+const meta = {
+    title: 'Forms/RankList',
+    component: RankList,
+    argTypes: {
+        'update:modelValue': {
+            description: 'Event handler called when the order changes.',
+            table: {
+                category: 'events',
+                type: { summary: '(value: string[]) => void' }
+            }
+        }
+    },
+} satisfies Meta<typeof RankList>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const seasons = [
+    { value: 'spring', label: 'Spring' },
+    { value: 'summer', label: 'Summer' },
+    { value: 'autumn', label: 'Autumn' },
+    { value: 'winter', label: 'Winter' },
+];
+
+const defaultCode = `
+<RankList v-model="order" :options="options" />
+`;
+
+export const _DocsIntro: Story = {
+    tags: ['!dev'],
+    parameters: {
+        docs: {
+            source: { code: defaultCode }
+        }
+    },
+    render: () => ({
+        components: { RankList },
+        setup() {
+            const order = ref([]);
+            return { order, options: seasons };
+        },
+        template: defaultCode,
+    }),
+};
+
+const orderedCode = `
+<Field label="Rank your favourite seasons">
+    <RankList v-model="order" :options="options" />
+</Field>
+`;
+
+export const _ExistingOrder: Story = {
+    tags: ['!dev'],
+    parameters: {
+        docs: {
+            source: { code: orderedCode }
+        }
+    },
+    render: () => ({
+        components: { Field, RankList },
+        setup() {
+            const order = ref(['summer', 'spring', 'winter', 'autumn']);
+            return { order, options: seasons };
+        },
+        template: orderedCode,
+    }),
+};
+
+const disabledCode = `
+<RankList :model-value="order" :options="options" disabled />
+`;
+
+export const _Disabled: Story = {
+    tags: ['!dev'],
+    parameters: {
+        docs: {
+            source: { code: disabledCode }
+        }
+    },
+    render: () => ({
+        components: { RankList },
+        setup() {
+            return { order: ['winter', 'autumn', 'summer', 'spring'], options: seasons };
+        },
+        template: disabledCode,
+    }),
+};
+
+export const TestFallsBackToOptionOrder: Story = {
+    tags: ['!dev', 'test'],
+    render: () => ({
+        components: { RankList },
+        setup() {
+            return { options: seasons };
+        },
+        template: `<RankList :options="options" />`,
+    }),
+    play: async ({ canvasElement }) => {
+        const items = within(canvasElement).getAllByRole('listitem');
+
+        expect(items.map((item) => item.textContent?.trim())).toEqual(['Spring', 'Summer', 'Autumn', 'Winter']);
+    },
+};
+
+export const TestTypingARankReorders: Story = {
+    tags: ['!dev', 'test'],
+    args: {
+        'onUpdate:modelValue': fn(),
+    },
+    render: (args) => ({
+        components: { RankList },
+        setup() {
+            return { options: seasons, onUpdate: args['onUpdate:modelValue'] };
+        },
+        template: `<RankList :options="options" @update:modelValue="onUpdate" />`,
+    }),
+    play: async ({ canvasElement, args }) => {
+        const input = within(canvasElement).getByLabelText('Rank Winter') as HTMLInputElement;
+
+        await userEvent.clear(input);
+        await userEvent.type(input, '1');
+        await userEvent.tab();
+
+        expect(args['onUpdate:modelValue']).toHaveBeenCalledWith(['winter', 'spring', 'summer', 'autumn']);
+    },
+};
+
+export const TestOutOfRangeRankIsClamped: Story = {
+    tags: ['!dev', 'test'],
+    args: {
+        'onUpdate:modelValue': fn(),
+    },
+    render: (args) => ({
+        components: { RankList },
+        setup() {
+            return { options: seasons, onUpdate: args['onUpdate:modelValue'] };
+        },
+        template: `<RankList :options="options" @update:modelValue="onUpdate" />`,
+    }),
+    play: async ({ canvasElement, args }) => {
+        const input = within(canvasElement).getByLabelText('Rank Spring') as HTMLInputElement;
+
+        await userEvent.clear(input);
+        await userEvent.type(input, '9');
+        await userEvent.tab();
+
+        expect(args['onUpdate:modelValue']).toHaveBeenCalledWith(['summer', 'autumn', 'winter', 'spring']);
+        expect(input.value).toBe('4');
+    },
+};
diff --git a/resources/js/stories/docs/RankList.mdx b/resources/js/stories/docs/RankList.mdx
new file mode 100644
index 00000000000..fb868d47ccf
--- /dev/null
+++ b/resources/js/stories/docs/RankList.mdx
@@ -0,0 +1,21 @@
+import { Canvas, Meta, ArgTypes } from '@storybook/addon-docs/blocks';
+import * as RankListStories from '../RankList.stories';
+
+<Meta of={RankListStories} />
+
+# RankList
+An ordered list of items that can be rearranged by dragging, or by typing a position into each item's rank input.
+
+The value is an array of option values in their ranked order. When it's empty, or missing some of the options, the list falls back to the order the options were given in.
+<Canvas of={RankListStories._DocsIntro} sourceState={'shown'} />
+
+## Existing order
+Pass an order to start from. The drag handles highlight once the list differs from the original order.
+<Canvas of={RankListStories._ExistingOrder} sourceState={'shown'} />
+
+## Disabled
+A disabled list can't be reordered. The rank inputs are replaced with plain numbers.
+<Canvas of={RankListStories._Disabled} sourceState={'shown'} />
+
+## Arguments
+<ArgTypes of={RankListStories} />
diff --git a/resources/js/tests/Package.test.js b/resources/js/tests/Package.test.js
index ec6295c2922..eadcea6081e 100644
--- a/resources/js/tests/Package.test.js
+++ b/resources/js/tests/Package.test.js
@@ -184,6 +184,7 @@ it('exports ui', async () => {
         'Popover',
         'Radio',
         'RadioGroup',
+        'RankList',
         'Select',
         'Separator',
         'Skeleton',

From c5b8b2dbd9c0c94e91f1edea7cfc0d59cb562ff3 Mon Sep 17 00:00:00 2001
From: Duncan McClean <duncan@duncanmcclean.com>
Date: Thu, 23 Jul 2026 15:54:10 +0100
Subject: [PATCH 3/5] extract `ChoiceList` into a ui component

from the image choice fieldtype
---
 packages/cms/src/ui.js                        |   1 +
 resources/js/bootstrap/cms/ui.js              |   1 +
 .../fieldtypes/ImageChoiceFieldtype.vue       | 138 +++---------
 .../components/ui/ChoiceGrid/ChoiceGrid.vue   | 130 +++++++++++
 resources/js/components/ui/index.js           |   1 +
 resources/js/stories/ChoiceGrid.stories.ts    | 211 ++++++++++++++++++
 resources/js/stories/docs/ChoiceGrid.mdx      |  29 +++
 resources/js/tests/Package.test.js            |   1 +
 8 files changed, 411 insertions(+), 101 deletions(-)
 create mode 100644 resources/js/components/ui/ChoiceGrid/ChoiceGrid.vue
 create mode 100644 resources/js/stories/ChoiceGrid.stories.ts
 create mode 100644 resources/js/stories/docs/ChoiceGrid.mdx

diff --git a/packages/cms/src/ui.js b/packages/cms/src/ui.js
index 564b4568c4d..1cce409c7f4 100644
--- a/packages/cms/src/ui.js
+++ b/packages/cms/src/ui.js
@@ -13,6 +13,7 @@ export const {
     CharacterCounter,
     Checkbox,
     CheckboxGroup,
+    ChoiceGrid,
     CodeEditor,
     Combobox,
     CommandPaletteItem,
diff --git a/resources/js/bootstrap/cms/ui.js b/resources/js/bootstrap/cms/ui.js
index c311a2eb888..a38890b0bf4 100644
--- a/resources/js/bootstrap/cms/ui.js
+++ b/resources/js/bootstrap/cms/ui.js
@@ -13,6 +13,7 @@ export {
     CharacterCounter,
     Checkbox,
     CheckboxGroup,
+    ChoiceGrid,
     CodeEditor,
     Combobox,
     CommandPaletteItem,
diff --git a/resources/js/components/fieldtypes/ImageChoiceFieldtype.vue b/resources/js/components/fieldtypes/ImageChoiceFieldtype.vue
index cbf8878bfe8..8ea477f8f64 100644
--- a/resources/js/components/fieldtypes/ImageChoiceFieldtype.vue
+++ b/resources/js/components/fieldtypes/ImageChoiceFieldtype.vue
@@ -1,115 +1,51 @@
 <script setup>
 import Fieldtype from '@/components/fieldtypes/fieldtype.js';
-import { Icon } from '@/components/ui';
-import { computed, ref, watch } from 'vue';
+import { ChoiceGrid } from '@/components/ui';
+import { __ } from '@/bootstrap/globals';
+import { computed } from 'vue';
 
 const emit = defineEmits(Fieldtype.emits);
 const props = defineProps(Fieldtype.props);
 const { expose, update, isReadOnly, name } = Fieldtype.use(emit, props);
 defineExpose(expose);
 
-const multiple = computed(() => Boolean(props.config.multiple));
-const isDisabled = computed(() => props.config.disabled || isReadOnly.value);
-const options = computed(() => props.meta?.options ?? []);
-const columns = computed(() => props.config.columns ?? 3);
-const aspectRatio = computed(() => props.config.aspect_ratio ?? '16/9');
-const gap = computed(() => props.config.gap ?? 3);
-
-const selectedValues = ref(props.value);
-
-const cardClasses = [
-    'flex flex-col gap-2 h-full p-1 pb-2 rounded-lg border shadow-ui-xs',
-    'border-gray-300 bg-white',
-    'dark:border-gray-700 dark:bg-gray-900',
-    'hover:border-gray-400 dark:hover:border-gray-700',
-    'peer-checked:border-primary peer-checked:ring-[1px] peer-checked:ring-primary',
-    'peer-focus-visible:focus-outline peer-focus-visible:transition-none',
-];
+const gaps = {
+    2: 'sm',
+    3: 'base',
+    4: 'lg',
+};
 
-const gridClass = computed(() => ({
-    1: 'grid-cols-1',
-    2: 'grid-cols-2',
-    3: 'grid-cols-3',
-    4: 'grid-cols-4',
-})[columns.value] ?? 'grid-cols-3');
-
-const gapClass = computed(() => ({
-    2: 'gap-2',
-    3: 'gap-3',
-    4: 'gap-4',
-})[gap.value] ?? 'gap-3');
-
-function isSelected(key) {
-    return selectedValues.value.includes(key);
-}
-
-function toggleOption(key) {
-    if (isDisabled.value) return;
-
-    if (isSelected(key)) {
-        selectedValues.value = selectedValues.value.filter((v) => v !== key);
-    } else if (multiple.value) {
-        selectedValues.value = [...selectedValues.value, key];
-    } else {
-        selectedValues.value = [key];
-    }
-
-    update(selectedValues.value);
+const multiple = computed(() => Boolean(props.config.multiple));
+const label = computed(() => (props.config.display ? __(props.config.display) : null));
+const gap = computed(() => gaps[props.config.gap] ?? 'base');
+
+const options = computed(() =>
+    (props.meta?.options ?? []).map((option) => ({
+        value: option.key,
+        label: option.label ? __(option.label) : null,
+        image: option.image,
+        badge: option.letter,
+    })),
+);
+
+const selected = computed(() => (multiple.value ? props.value : (props.value?.[0] ?? null)));
+
+function updateSelected(value) {
+    update(multiple.value ? value : [value]);
 }
-
-watch(() => props.value, (value) => selectedValues.value = value);
 </script>
 
 <template>
-    <div
-        class="grid"
-        :class="[gapClass, gridClass]"
-        :role="multiple ? 'group' : 'radiogroup'"
-    >
-        <label
-            v-for="option in options"
-            :key="option.key"
-            class="group cursor-pointer has-disabled:cursor-not-allowed has-disabled:opacity-60"
-        >
-            <input
-                class="peer sr-only"
-                :type="multiple ? 'checkbox' : 'radio'"
-                :name="multiple ? `${name}[]` : name"
-                :value="option.key"
-                :checked="isSelected(option.key)"
-                :disabled="isDisabled"
-                @change="toggleOption(option.key)"
-            >
-            <span :class="cardClasses">
-                <span
-                    class="flex items-center justify-center overflow-hidden rounded-md bg-gray-100 dark:bg-gray-800"
-                    :style="{ aspectRatio }"
-                >
-                    <img
-                        v-if="option.image"
-                        class="block size-full object-cover"
-                        :src="option.image"
-                        :alt="option.label"
-                    >
-                    <span v-else class="flex size-full items-center justify-center" aria-hidden="true">
-                        <Icon name="image" class="size-6 text-gray-400" />
-                    </span>
-                </span>
-                <span
-                    v-if="option.label"
-                    class="flex items-center justify-center gap-2"
-                >
-                    <span
-                        v-if="option.letter"
-                        class="flex size-6 shrink-0 items-center justify-center rounded-md border border-gray-300 bg-white text-xs font-bold text-gray-800 dark:border-gray-600 dark:bg-gray-900 dark:text-gray-200"
-                    >
-                        {{ option.letter }}
-                    </span>
-                    <span class="text-xs text-gray-800 dark:text-gray-200" style="text-box-trim: trim-start;">
-                        {{ __(option.label) }}
-                    </span>
-                </span>
-            </span>
-        </label>
-    </div>
+    <ChoiceGrid
+        :model-value="selected"
+        :options
+        :multiple
+        :name
+        :label
+        :gap
+        :columns="config.columns ?? 3"
+        :aspect-ratio="config.aspect_ratio ?? '16/9'"
+        :disabled="config.disabled || isReadOnly"
+        @update:model-value="updateSelected"
+    />
 </template>
diff --git a/resources/js/components/ui/ChoiceGrid/ChoiceGrid.vue b/resources/js/components/ui/ChoiceGrid/ChoiceGrid.vue
new file mode 100644
index 00000000000..7a30aeed004
--- /dev/null
+++ b/resources/js/components/ui/ChoiceGrid/ChoiceGrid.vue
@@ -0,0 +1,130 @@
+<script setup>
+import { computed, useId } from 'vue';
+import { cva } from 'cva';
+import Icon from '../Icon/Icon.vue';
+
+const props = defineProps({
+    /** The shape of each option's image area, e.g. `16/9`. */
+    aspectRatio: { type: String, default: '16/9' },
+    /** How many options appear per row. */
+    columns: { type: Number, default: 3 },
+    /** Whether the choices are disabled. */
+    disabled: { type: Boolean, default: false },
+    /** Controls the spacing between options. <br><br> Options: `sm`, `base`, `lg` */
+    gap: {
+        type: String,
+        default: 'base',
+        validator: (value) => ['sm', 'base', 'lg'].includes(value),
+    },
+    /** Accessible label for the group of choices. */
+    label: { type: String, default: null },
+    /** The controlled value. An array when `multiple`, otherwise a single value. */
+    modelValue: { type: [String, Number, Array], default: null },
+    /** Whether more than one option can be selected. */
+    multiple: { type: Boolean, default: false },
+    /** Name attribute for the choices. */
+    name: { type: String, default: () => useId() },
+    /** The selectable options. Each option supports `value`, `label`, `image` and `badge`. */
+    options: { type: Array, default: () => [] },
+});
+
+const emit = defineEmits(['update:modelValue']);
+
+const gridClasses = cva({
+    base: 'grid',
+    variants: {
+        gap: {
+            sm: 'gap-2',
+            base: 'gap-3',
+            lg: 'gap-4',
+        },
+    },
+})({ ...props });
+
+const cardClasses = [
+    'flex flex-col gap-2 h-full p-1 pb-2 rounded-lg border shadow-ui-xs',
+    'border-gray-300 bg-white',
+    'dark:border-gray-700 dark:bg-gray-900',
+    'hover:border-gray-400 dark:hover:border-gray-700',
+    'peer-checked:border-primary peer-checked:ring-[1px] peer-checked:ring-primary',
+    'peer-focus-visible:focus-outline peer-focus-visible:transition-none',
+];
+
+const selected = computed(() => {
+    if (props.modelValue == null) return [];
+
+    return Array.isArray(props.modelValue) ? props.modelValue : [props.modelValue];
+});
+
+function isSelected(value) {
+    return selected.value.includes(value);
+}
+
+function select(value) {
+    if (props.disabled) return;
+
+    if (!props.multiple) {
+        emit('update:modelValue', value);
+
+        return;
+    }
+
+    emit(
+        'update:modelValue',
+        isSelected(value) ? selected.value.filter((item) => item !== value) : [...selected.value, value],
+    );
+}
+</script>
+
+<template>
+    <div
+        :class="gridClasses"
+        :style="{ gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))` }"
+        :role="multiple ? 'group' : 'radiogroup'"
+        :aria-label="label"
+        data-ui-choice-grid
+    >
+        <label
+            v-for="option in options"
+            :key="option.value"
+            class="group cursor-pointer has-disabled:cursor-not-allowed has-disabled:opacity-60"
+        >
+            <input
+                class="peer sr-only"
+                :type="multiple ? 'checkbox' : 'radio'"
+                :name="multiple ? `${name}[]` : name"
+                :value="option.value"
+                :checked="isSelected(option.value)"
+                :disabled="disabled"
+                @change="select(option.value)"
+            />
+            <span :class="cardClasses">
+                <span
+                    class="flex items-center justify-center overflow-hidden rounded-md bg-gray-100 dark:bg-gray-800"
+                    :style="{ aspectRatio }"
+                >
+                    <img
+                        v-if="option.image"
+                        class="block size-full object-cover"
+                        :src="option.image"
+                        :alt="option.label"
+                    />
+                    <span v-else class="flex size-full items-center justify-center" aria-hidden="true">
+                        <Icon name="media-image-photo-focus-frame" class="size-6 text-gray-400" />
+                    </span>
+                </span>
+                <span v-if="option.label" class="flex items-center justify-center gap-2">
+                    <span
+                        v-if="option.badge"
+                        class="flex size-6 shrink-0 items-center justify-center rounded-md border border-gray-300 bg-white text-xs font-bold text-gray-800 dark:border-gray-600 dark:bg-gray-900 dark:text-gray-200"
+                    >
+                        {{ option.badge }}
+                    </span>
+                    <span class="text-xs text-gray-800 dark:text-gray-200" style="text-box-trim: trim-start">
+                        {{ option.label }}
+                    </span>
+                </span>
+            </span>
+        </label>
+    </div>
+</template>
diff --git a/resources/js/components/ui/index.js b/resources/js/components/ui/index.js
index 546d2349337..2216de92575 100644
--- a/resources/js/components/ui/index.js
+++ b/resources/js/components/ui/index.js
@@ -11,6 +11,7 @@ export { default as CardPanel } from './Card/Panel.vue';
 export { default as CharacterCounter } from './CharacterCounter.vue';
 export { default as Checkbox } from './Checkbox/Item.vue';
 export { default as CheckboxGroup } from './Checkbox/Group.vue';
+export { default as ChoiceGrid } from './ChoiceGrid/ChoiceGrid.vue';
 export { default as CodeEditor } from './CodeEditor.vue';
 export { default as Combobox } from './Combobox/Combobox.vue';
 export { default as ConfirmationModal } from './Modal/ConfirmationModal.vue';
diff --git a/resources/js/stories/ChoiceGrid.stories.ts b/resources/js/stories/ChoiceGrid.stories.ts
new file mode 100644
index 00000000000..2bc8cf12aa1
--- /dev/null
+++ b/resources/js/stories/ChoiceGrid.stories.ts
@@ -0,0 +1,211 @@
+import type {Meta, StoryObj} from '@storybook/vue3';
+import {ref} from 'vue';
+import {expect, fn, userEvent, within} from 'storybook/test';
+import {ChoiceGrid} from '@ui';
+
+const meta = {
+    title: 'Forms/ChoiceGrid',
+    component: ChoiceGrid,
+    argTypes: {
+        gap: {
+            control: 'select',
+            options: ['sm', 'base', 'lg'],
+        },
+        'update:modelValue': {
+            description: 'Event handler called when the selection changes.',
+            table: {
+                category: 'events',
+                type: { summary: '(value: string | string[]) => void' }
+            }
+        }
+    },
+} satisfies Meta<typeof ChoiceGrid>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const seasons = [
+    { value: 'spring', label: 'Spring', image: 'https://picsum.photos/seed/choice-grid-spring/640/480' },
+    { value: 'summer', label: 'Summer', image: 'https://picsum.photos/seed/choice-grid-summer/640/480' },
+    { value: 'autumn', label: 'Autumn', image: 'https://picsum.photos/seed/choice-grid-autumn/640/480' },
+    { value: 'winter', label: 'Winter', image: 'https://picsum.photos/seed/choice-grid-winter/640/480' },
+];
+
+const defaultCode = `
+<ChoiceGrid v-model="season" :options="options" :columns="2" label="Pick a season" />
+`;
+
+export const _DocsIntro: Story = {
+    tags: ['!dev'],
+    parameters: {
+        docs: {
+            source: { code: defaultCode }
+        }
+    },
+    render: () => ({
+        components: { ChoiceGrid },
+        setup() {
+            const season = ref('summer');
+            return { season, options: seasons };
+        },
+        template: defaultCode,
+    }),
+};
+
+const multipleCode = `
+<ChoiceGrid v-model="chosen" :options="options" :columns="2" multiple label="Pick your seasons" />
+`;
+
+export const _Multiple: Story = {
+    tags: ['!dev'],
+    parameters: {
+        docs: {
+            source: { code: multipleCode }
+        }
+    },
+    render: () => ({
+        components: { ChoiceGrid },
+        setup() {
+            const chosen = ref(['spring', 'autumn']);
+            return { chosen, options: seasons };
+        },
+        template: multipleCode,
+    }),
+};
+
+const badgesCode = `
+<ChoiceGrid v-model="answer" :options="options" :columns="3" label="Which layout?" />
+`;
+
+export const _Badges: Story = {
+    tags: ['!dev'],
+    parameters: {
+        docs: {
+            source: { code: badgesCode }
+        }
+    },
+    render: () => ({
+        components: { ChoiceGrid },
+        setup() {
+            const answer = ref(null);
+            const options = seasons.slice(0, 3).map((option, index) => ({
+                ...option,
+                badge: String.fromCharCode(65 + index),
+            }));
+            return { answer, options };
+        },
+        template: badgesCode,
+    }),
+};
+
+const aspectRatioCode = `
+<ChoiceGrid v-model="season" :options="options" :columns="4" aspect-ratio="1/1" gap="lg" />
+`;
+
+export const _AspectRatio: Story = {
+    tags: ['!dev'],
+    parameters: {
+        docs: {
+            source: { code: aspectRatioCode }
+        }
+    },
+    render: () => ({
+        components: { ChoiceGrid },
+        setup() {
+            const season = ref('winter');
+            return { season, options: seasons };
+        },
+        template: aspectRatioCode,
+    }),
+};
+
+const placeholderCode = `
+<ChoiceGrid v-model="answer" :options="options" :columns="2" />
+`;
+
+export const _WithoutImages: Story = {
+    tags: ['!dev'],
+    parameters: {
+        docs: {
+            source: { code: placeholderCode }
+        }
+    },
+    render: () => ({
+        components: { ChoiceGrid },
+        setup() {
+            const answer = ref(null);
+            const options = [
+                { value: 'one', label: 'Awaiting artwork' },
+                { value: 'two', label: 'Also awaiting artwork' },
+            ];
+            return { answer, options };
+        },
+        template: placeholderCode,
+    }),
+};
+
+export const TestSelectsSingleOption: Story = {
+    tags: ['!dev', 'test'],
+    args: {
+        'onUpdate:modelValue': fn(),
+    },
+    render: (args) => ({
+        components: { ChoiceGrid },
+        setup() {
+            return { options: seasons, onUpdate: args['onUpdate:modelValue'] };
+        },
+        template: `<ChoiceGrid :options="options" @update:modelValue="onUpdate" />`,
+    }),
+    play: async ({ canvasElement, args }) => {
+        const canvas = within(canvasElement);
+
+        await userEvent.click(canvas.getByText('Autumn'));
+
+        expect(args['onUpdate:modelValue']).toHaveBeenCalledWith('autumn');
+        expect(canvas.getAllByRole('radio')).toHaveLength(4);
+    },
+};
+
+export const TestTogglesMultipleOptions: Story = {
+    tags: ['!dev', 'test'],
+    args: {
+        'onUpdate:modelValue': fn(),
+    },
+    render: (args) => ({
+        components: { ChoiceGrid },
+        setup() {
+            return { options: seasons, onUpdate: args['onUpdate:modelValue'] };
+        },
+        template: `<ChoiceGrid :model-value="['spring']" :options="options" multiple @update:modelValue="onUpdate" />`,
+    }),
+    play: async ({ canvasElement, args }) => {
+        const canvas = within(canvasElement);
+
+        await userEvent.click(canvas.getByText('Winter'));
+        expect(args['onUpdate:modelValue']).toHaveBeenCalledWith(['spring', 'winter']);
+
+        await userEvent.click(canvas.getByText('Spring'));
+        expect(args['onUpdate:modelValue']).toHaveBeenCalledWith([]);
+    },
+};
+
+export const TestDisabledOptionsCannotBeSelected: Story = {
+    tags: ['!dev', 'test'],
+    args: {
+        'onUpdate:modelValue': fn(),
+    },
+    render: (args) => ({
+        components: { ChoiceGrid },
+        setup() {
+            return { options: seasons, onUpdate: args['onUpdate:modelValue'] };
+        },
+        template: `<ChoiceGrid :options="options" disabled @update:modelValue="onUpdate" />`,
+    }),
+    play: async ({ canvasElement, args }) => {
+        const canvas = within(canvasElement);
+
+        await userEvent.click(canvas.getByText('Summer'));
+
+        expect(args['onUpdate:modelValue']).not.toHaveBeenCalled();
+    },
+};
diff --git a/resources/js/stories/docs/ChoiceGrid.mdx b/resources/js/stories/docs/ChoiceGrid.mdx
new file mode 100644
index 00000000000..928a428731c
--- /dev/null
+++ b/resources/js/stories/docs/ChoiceGrid.mdx
@@ -0,0 +1,29 @@
+import { Canvas, Meta, ArgTypes } from '@storybook/addon-docs/blocks';
+import * as ChoiceGridStories from '../ChoiceGrid.stories';
+
+<Meta of={ChoiceGridStories} />
+
+# ChoiceGrid
+A grid of image-led cards for picking between visual options. Each card is a real radio or checkbox, so selection works with the keyboard and inside a regular form.
+
+Options are objects with a `value`, and optionally a `label`, `image` and `badge`.
+<Canvas of={ChoiceGridStories._DocsIntro} sourceState={'shown'} />
+
+## Multiple
+Add `multiple` to allow more than one selection. The value becomes an array of the selected option values.
+<Canvas of={ChoiceGridStories._Multiple} sourceState={'shown'} />
+
+## Badges
+An option's `badge` is shown alongside its label. Handy for lettering or numbering the choices.
+<Canvas of={ChoiceGridStories._Badges} sourceState={'shown'} />
+
+## Columns, gaps and aspect ratios
+Use `columns` to set how many options appear per row, `gap` to control the spacing between them, and `aspect-ratio` to change the shape of each image area.
+<Canvas of={ChoiceGridStories._AspectRatio} sourceState={'shown'} />
+
+## Missing images
+Options without an `image` fall back to a placeholder, so a partially configured grid still lines up.
+<Canvas of={ChoiceGridStories._WithoutImages} sourceState={'shown'} />
+
+## Arguments
+<ArgTypes of={ChoiceGridStories} />
diff --git a/resources/js/tests/Package.test.js b/resources/js/tests/Package.test.js
index eadcea6081e..5d95c36e2ca 100644
--- a/resources/js/tests/Package.test.js
+++ b/resources/js/tests/Package.test.js
@@ -135,6 +135,7 @@ it('exports ui', async () => {
         'CharacterCounter',
         'Checkbox',
         'CheckboxGroup',
+        'ChoiceGrid',
         'CodeEditor',
         'Combobox',
         'ConfirmationModal',

From fe54a634b59c097547eda057fa20170a12772182 Mon Sep 17 00:00:00 2001
From: Duncan McClean <duncan@duncanmcclean.com>
Date: Thu, 23 Jul 2026 15:55:54 +0100
Subject: [PATCH 4/5] they don't need folders

---
 resources/js/components/ui/{ChoiceGrid => }/ChoiceGrid.vue | 2 +-
 resources/js/components/ui/{RankList => }/RankList.vue     | 4 ++--
 resources/js/components/ui/{StarRating => }/StarRating.vue | 2 +-
 resources/js/components/ui/index.js                        | 6 +++---
 4 files changed, 7 insertions(+), 7 deletions(-)
 rename resources/js/components/ui/{ChoiceGrid => }/ChoiceGrid.vue (99%)
 rename resources/js/components/ui/{RankList => }/RankList.vue (98%)
 rename resources/js/components/ui/{StarRating => }/StarRating.vue (99%)

diff --git a/resources/js/components/ui/ChoiceGrid/ChoiceGrid.vue b/resources/js/components/ui/ChoiceGrid.vue
similarity index 99%
rename from resources/js/components/ui/ChoiceGrid/ChoiceGrid.vue
rename to resources/js/components/ui/ChoiceGrid.vue
index 7a30aeed004..5b5aed3664e 100644
--- a/resources/js/components/ui/ChoiceGrid/ChoiceGrid.vue
+++ b/resources/js/components/ui/ChoiceGrid.vue
@@ -1,7 +1,7 @@
 <script setup>
 import { computed, useId } from 'vue';
 import { cva } from 'cva';
-import Icon from '../Icon/Icon.vue';
+import Icon from './Icon/Icon.vue';
 
 const props = defineProps({
     /** The shape of each option's image area, e.g. `16/9`. */
diff --git a/resources/js/components/ui/RankList/RankList.vue b/resources/js/components/ui/RankList.vue
similarity index 98%
rename from resources/js/components/ui/RankList/RankList.vue
rename to resources/js/components/ui/RankList.vue
index 103e6fbf694..fdfafb77af1 100644
--- a/resources/js/components/ui/RankList/RankList.vue
+++ b/resources/js/components/ui/RankList.vue
@@ -1,8 +1,8 @@
 <script setup>
 import { computed, ref, watch } from 'vue';
 import { SortableList } from '@/components/sortable/Sortable.js';
-import { __ } from '@/bootstrap/globals';
-import DragHandle from '../DragHandle.vue';
+import { __ } from '@/bootstrap/globals.js';
+import DragHandle from './DragHandle.vue';
 
 const props = defineProps({
     /** Whether the list can be reordered. */
diff --git a/resources/js/components/ui/StarRating/StarRating.vue b/resources/js/components/ui/StarRating.vue
similarity index 99%
rename from resources/js/components/ui/StarRating/StarRating.vue
rename to resources/js/components/ui/StarRating.vue
index 81a5095c365..947eff50e8e 100644
--- a/resources/js/components/ui/StarRating/StarRating.vue
+++ b/resources/js/components/ui/StarRating.vue
@@ -1,6 +1,6 @@
 <script setup>
 import { computed, ref, useId } from 'vue';
-import { __ } from '@/bootstrap/globals';
+import { __ } from '@/bootstrap/globals.js';
 
 const props = defineProps({
     /** Whether the rating is disabled. */
diff --git a/resources/js/components/ui/index.js b/resources/js/components/ui/index.js
index 2216de92575..504fc178fc1 100644
--- a/resources/js/components/ui/index.js
+++ b/resources/js/components/ui/index.js
@@ -11,7 +11,7 @@ export { default as CardPanel } from './Card/Panel.vue';
 export { default as CharacterCounter } from './CharacterCounter.vue';
 export { default as Checkbox } from './Checkbox/Item.vue';
 export { default as CheckboxGroup } from './Checkbox/Group.vue';
-export { default as ChoiceGrid } from './ChoiceGrid/ChoiceGrid.vue';
+export { default as ChoiceGrid } from './ChoiceGrid.vue';
 export { default as CodeEditor } from './CodeEditor.vue';
 export { default as Combobox } from './Combobox/Combobox.vue';
 export { default as ConfirmationModal } from './Modal/ConfirmationModal.vue';
@@ -62,7 +62,7 @@ export { default as PanelHeader } from './Panel/Header.vue';
 export { default as Popover } from './Popover.vue';
 export { default as Radio } from './Radio/Item.vue';
 export { default as RadioGroup } from './Radio/Group.vue';
-export { default as RankList } from './RankList/RankList.vue';
+export { default as RankList } from './RankList.vue';
 export { default as Select } from './Select/Select.vue';
 export { default as Separator } from './Separator.vue';
 export { default as Slider } from './Slider/Slider.vue';
@@ -70,7 +70,7 @@ export { default as Skeleton } from './Skeleton.vue';
 export { default as SplitterGroup } from './Splitter/Group.vue';
 export { default as SplitterPanel } from './Splitter/Panel.vue';
 export { default as SplitterResizeHandle } from './Splitter/ResizeHandle.vue';
-export { default as StarRating } from './StarRating/StarRating.vue';
+export { default as StarRating } from './StarRating.vue';
 export { default as Subheading } from './Subheading.vue';
 export { default as Switch } from './Switch.vue';
 export { default as TabContent } from './Tabs/Content.vue';

From 5376a0fb64cdf13250b584788d7abb3c56a71c30 Mon Sep 17 00:00:00 2001
From: Duncan McClean <duncan@duncanmcclean.com>
Date: Thu, 23 Jul 2026 16:18:32 +0100
Subject: [PATCH 5/5] use inline images in `ChoiceGrid` stories

---
 resources/js/stories/ChoiceGrid.stories.ts | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/resources/js/stories/ChoiceGrid.stories.ts b/resources/js/stories/ChoiceGrid.stories.ts
index 2bc8cf12aa1..84074ba5248 100644
--- a/resources/js/stories/ChoiceGrid.stories.ts
+++ b/resources/js/stories/ChoiceGrid.stories.ts
@@ -24,11 +24,16 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
+// Inline, so the stories don't depend on the network when they run in CI.
+const image = (hue: number) => `data:image/svg+xml,${encodeURIComponent(
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 480"><rect width="640" height="480" fill="hsl(${hue} 60% 70%)"/></svg>`
+)}`;
+
 const seasons = [
-    { value: 'spring', label: 'Spring', image: 'https://picsum.photos/seed/choice-grid-spring/640/480' },
-    { value: 'summer', label: 'Summer', image: 'https://picsum.photos/seed/choice-grid-summer/640/480' },
-    { value: 'autumn', label: 'Autumn', image: 'https://picsum.photos/seed/choice-grid-autumn/640/480' },
-    { value: 'winter', label: 'Winter', image: 'https://picsum.photos/seed/choice-grid-winter/640/480' },
+    { value: 'spring', label: 'Spring', image: image(110) },
+    { value: 'summer', label: 'Summer', image: image(45) },
+    { value: 'autumn', label: 'Autumn', image: image(20) },
+    { value: 'winter', label: 'Winter', image: image(210) },
 ];
 
 const defaultCode = `