Add scroll-snap utilities (#5637)

Co-authored-by: Adam Wathan <4323180+adamwathan@users.noreply.github.com>
Co-authored-by: Peter Jonsson <4572231+95jonpet@users.noreply.github.com>
Co-authored-by: Enzo Innocenzi <enzo@innocenzi.dev>

src/corePlugins.js

@@ -813,6 +813,76 @@ export default {
     })
   },
 
+  scrollSnapType: ({ addUtilities, addBase }) => {
+    addBase({
+      '@defaults scroll-snap-type': {
+        '--tw-scroll-snap-strictness': 'proximity',
+      },
+    })
+
+    addUtilities({
+      '.snap-none': { 'scroll-snap-type': 'none' },
+      '.snap-x': {
+        '@defaults scroll-snap-type': {},
+        'scroll-snap-type': 'x var(--tw-scroll-snap-strictness)',
+      },
+      '.snap-y': {
+        '@defaults scroll-snap-type': {},
+        'scroll-snap-type': 'y var(--tw-scroll-snap-strictness)',
+      },
+      '.snap-both': {
+        '@defaults scroll-snap-type': {},
+        'scroll-snap-type': 'both var(--tw-scroll-snap-strictness)',
+      },
+      '.snap-mandatory': { '--tw-scroll-snap-strictness': 'mandatory' },
+      '.snap-proximity': { '--tw-scroll-snap-strictness': 'proximity' },
+    })
+  },
+
+  scrollSnapAlign: ({ addUtilities }) => {
+    addUtilities({
+      '.snap-start': { 'scroll-snap-align': 'start' },
+      '.snap-end': { 'scroll-snap-align': 'end' },
+      '.snap-center': { 'scroll-snap-align': 'center' },
+      '.snap-align-none': { 'scroll-snap-align': 'none' },
+    })
+  },
+
+  scrollSnapStop: ({ addUtilities }) => {
+    addUtilities({
+      '.snap-normal': { 'scroll-snap-stop': 'normal' },
+      '.snap-always': { 'scroll-snap-stop': 'always' },
+    })
+  },
+
+  scrollMargin: createUtilityPlugin('scrollMargin', [
+    ['scroll-m', ['scroll-margin']],
+    [
+      ['scroll-mx', ['scroll-margin-left', 'scroll-margin-right']],
+      ['scroll-my', ['scroll-margin-top', 'scroll-margin-bottom']],
+    ],
+    [
+      ['scroll-mt', ['scroll-margin-top']],
+      ['scroll-mr', ['scroll-margin-right']],
+      ['scroll-mb', ['scroll-margin-bottom']],
+      ['scroll-ml', ['scroll-margin-left']],
+    ],
+  ]),
+
+  scrollPadding: createUtilityPlugin('scrollPadding', [
+    ['scroll-p', ['scroll-padding']],
+    [
+      ['scroll-px', ['scroll-padding-left', 'scroll-padding-right']],
+      ['scroll-py', ['scroll-padding-top', 'scroll-padding-bottom']],
+    ],
+    [
+      ['scroll-pt', ['scroll-padding-top']],
+      ['scroll-pr', ['scroll-padding-right']],
+      ['scroll-pb', ['scroll-padding-bottom']],
+      ['scroll-pl', ['scroll-padding-left']],
+    ],
+  ]),
+
   listStylePosition: ({ addUtilities }) => {
     addUtilities({
       '.list-inside': { 'list-style-position': 'inside' },

stubs/defaultConfig.stub.js

@@ -711,6 +711,11 @@ module.exports = {
       125: '1.25',
       150: '1.5',
     },
+    scrollMargin: (theme, { negative }) => ({
+      ...theme('spacing'),
+      ...negative(theme('spacing')),
+    }),
+    scrollPadding: (theme) => theme('spacing'),
     sepia: {
       0: '0',
       DEFAULT: '100%',

tests/arbitrary-values.test.css

@@ -307,6 +307,58 @@
 .cursor-\[var\(--value\)\] {
   cursor: var(--value);
 }
+.scroll-m-\[7px\] {
+  scroll-margin: 7px;
+}
+.scroll-mx-\[7px\] {
+  scroll-margin-left: 7px;
+  scroll-margin-right: 7px;
+}
+.scroll-my-\[7px\] {
+  scroll-margin-top: 7px;
+  scroll-margin-bottom: 7px;
+}
+.scroll-mt-\[7px\] {
+  scroll-margin-top: 7px;
+}
+.scroll-mr-\[7px\] {
+  scroll-margin-right: 7px;
+}
+.scroll-mb-\[7px\] {
+  scroll-margin-bottom: 7px;
+}
+.scroll-ml-\[7px\] {
+  scroll-margin-left: 7px;
+}
+.scroll-mt-\[var\(--scroll-margin\)\] {
+  scroll-margin-top: var(--scroll-margin);
+}
+.scroll-p-\[7px\] {
+  scroll-padding: 7px;
+}
+.scroll-px-\[7px\] {
+  scroll-padding-left: 7px;
+  scroll-padding-right: 7px;
+}
+.scroll-py-\[7px\] {
+  scroll-padding-top: 7px;
+  scroll-padding-bottom: 7px;
+}
+.scroll-pt-\[7px\] {
+  scroll-padding-top: 7px;
+}
+.scroll-pr-\[7px\] {
+  scroll-padding-right: 7px;
+}
+.scroll-pb-\[7px\] {
+  scroll-padding-bottom: 7px;
+}
+.scroll-pl-\[7px\] {
+  scroll-padding-left: 7px;
+}
+.scroll-pt-\[var\(--scroll-padding\)\] {
+  scroll-padding-top: var(--scroll-padding);
+}
 .list-\[\'\\1f44d\'\] {
   list-style-type: '\1F44D';
 }

tests/arbitrary-values.test.html

@@ -103,6 +103,24 @@
     <div class="animate-[pong_1s_cubic-bezier(0,0,0.2,1)_infinite]"></div>
     <div class="animate-[var(--value)]"></div>
 
+    <div class="scroll-m-[7px]"></div>
+    <div class="scroll-mx-[7px]"></div>
+    <div class="scroll-my-[7px]"></div>
+    <div class="scroll-mt-[7px]"></div>
+    <div class="scroll-mr-[7px]"></div>
+    <div class="scroll-mb-[7px]"></div>
+    <div class="scroll-ml-[7px]"></div>
+    <div class="scroll-mt-[var(--scroll-margin)]"></div>
+
+    <div class="scroll-p-[7px]"></div>
+    <div class="scroll-px-[7px]"></div>
+    <div class="scroll-py-[7px]"></div>
+    <div class="scroll-pt-[7px]"></div>
+    <div class="scroll-pr-[7px]"></div>
+    <div class="scroll-pb-[7px]"></div>
+    <div class="scroll-pl-[7px]"></div>
+    <div class="scroll-pt-[var(--scroll-padding)]"></div>
+
     <div class="cursor-[pointer]"></div>
     <div class="cursor-[url(hand.cur)_2_2,pointer]"></div>
     <div class="cursor-[var(--value)]"></div>

tests/basic-usage.test.css

@@ -11,6 +11,7 @@
   --tw-transform: translateX(var(--tw-translate-x)) translateY(var(--tw-translate-y))
     rotate(var(--tw-rotate)) skewX(var(--tw-skew-x)) skewY(var(--tw-skew-y))
     scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y));
+  --tw-scroll-snap-strictness: proximity;
   --tw-border-opacity: 1;
   border-color: rgb(229 231 235 / var(--tw-border-opacity));
   --tw-ring-offset-shadow: 0 0 #0000;
@@ -311,6 +312,24 @@
 .resize-none {
   resize: none;
 }
+.snap-x {
+  scroll-snap-type: x var(--tw-scroll-snap-strictness);
+}
+.snap-mandatory {
+  --tw-scroll-snap-strictness: mandatory;
+}
+.snap-center {
+  scroll-snap-align: center;
+}
+.snap-always {
+  scroll-snap-stop: always;
+}
+.scroll-mt-6 {
+  scroll-margin-top: 1.5rem;
+}
+.scroll-p-6 {
+  scroll-padding: 1.5rem;
+}
 .list-inside {
   list-style-position: inside;
 }

tests/basic-usage.test.html

@@ -110,6 +110,10 @@
     <div class="pointer-events-none"></div>
     <div class="absolute"></div>
     <div class="resize-none"></div>
+    <div class="snap-x snap-mandatory"></div>
+    <div class="snap-center snap-always"></div>
+    <div class="scroll-mt-6"></div>
+    <div class="scroll-p-6"></div>
     <div class="ring-white"></div>
     <div class="ring-offset-blue-300"></div>
     <div class="ring-offset-2"></div>