diff --git a/.changeset/rich-cooks-attend.md b/.changeset/rich-cooks-attend.md
new file mode 100644
index 00000000000..53d5e5ca698
--- /dev/null
+++ b/.changeset/rich-cooks-attend.md
@@ -0,0 +1,5 @@
+---
+'polaris.shopify.com': patch
+---
+
+Update `Columns` component docs
diff --git a/polaris.shopify.com/content/components/columns.md b/polaris.shopify.com/content/components/columns.md
index 980268c77f5..d35ea1b6299 100644
--- a/polaris.shopify.com/content/components/columns.md
+++ b/polaris.shopify.com/content/components/columns.md
@@ -1,6 +1,6 @@
---
title: Columns
-description: Use to lay out a vertical row of components with equal spacing between and wrapping onto multiple lines.
+description: Displays content horizontally in one or more columns with equal spacing between.
category: Structure
keywords:
- layout
@@ -10,8 +10,23 @@ status:
examples:
- fileName: columns-default.tsx
title: Default
+ description: >-
+ By default, there are 6 columns with 16px spacing between them.
- fileName: columns-with-varying-spacing.tsx
- title: With varying spacing
- - fileName: columns-with-free-and-fixed-widths.tsx
- title: With free and fixed widths
+ title: Spacing
+ description: >-
+ Use the spacing prop to set the amount of space between columns.
+ - fileName: columns-with-fixed-widths.tsx
+ title: Column width
+ description: >-
+ Individual column width can be adjusted.
+ - fileName: columns-with-set-number.tsx
+ title: Number of columns
+ description: >-
+ Use the columns prop to set the number and width of columns across breakpoints.
---
+
+## Related components
+
+- For more control over padding and widths, [use the Box](https://polaris.shopify.com/components/box) component
+- To lay out a set of smaller components horizontally, [use the Inline](https://polaris.shopify.com/components/inline) component
diff --git a/polaris.shopify.com/pages/examples/columns-default.tsx b/polaris.shopify.com/pages/examples/columns-default.tsx
index d7aabf7dbec..f5754a1423e 100644
--- a/polaris.shopify.com/pages/examples/columns-default.tsx
+++ b/polaris.shopify.com/pages/examples/columns-default.tsx
@@ -1,21 +1,45 @@
import React from 'react';
-import {Columns} from '@shopify/polaris';
+import {Columns, Text, Inline} from '@shopify/polaris';
import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
function ColumnsExample() {
return (
-
-
- Column one
- Column two
- Column three
- Column four
- Column five
- Column six
-
-
+
+
+
+
+
+
+
+
);
}
+const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
+ return (
+
+ );
+};
+
export default withPolarisExample(ColumnsExample);
diff --git a/polaris.shopify.com/pages/examples/columns-with-fixed-widths.tsx b/polaris.shopify.com/pages/examples/columns-with-fixed-widths.tsx
new file mode 100644
index 00000000000..a26f6491348
--- /dev/null
+++ b/polaris.shopify.com/pages/examples/columns-with-fixed-widths.tsx
@@ -0,0 +1,45 @@
+import React from 'react';
+import {Columns, Text, Inline} from '@shopify/polaris';
+
+import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
+
+function ColumnsWithFreeAndFixedWidthsExample() {
+ return (
+
+
+
+
+
+
+
+
+ );
+}
+
+const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
+ return (
+
+ );
+};
+
+export default withPolarisExample(ColumnsWithFreeAndFixedWidthsExample);
diff --git a/polaris.shopify.com/pages/examples/columns-with-free-and-fixed-widths.tsx b/polaris.shopify.com/pages/examples/columns-with-free-and-fixed-widths.tsx
deleted file mode 100644
index 6852bde8877..00000000000
--- a/polaris.shopify.com/pages/examples/columns-with-free-and-fixed-widths.tsx
+++ /dev/null
@@ -1,24 +0,0 @@
-import React from 'react';
-import {Columns} from '@shopify/polaris';
-
-import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
-
-function ColumnsWithFreeAndFixedWidthsExample() {
- return (
-
-
- Column one
- Column two
- Column three
- Column four
- Column five
- Column six
-
-
- );
-}
-
-export default withPolarisExample(ColumnsWithFreeAndFixedWidthsExample);
diff --git a/polaris.shopify.com/pages/examples/columns-with-set-number.tsx b/polaris.shopify.com/pages/examples/columns-with-set-number.tsx
new file mode 100644
index 00000000000..8afd0254db0
--- /dev/null
+++ b/polaris.shopify.com/pages/examples/columns-with-set-number.tsx
@@ -0,0 +1,67 @@
+import React from 'react';
+import {Columns, Text, Inline} from '@shopify/polaris';
+
+import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
+
+function ColumnsWithSetNumberExample() {
+ return (
+
+
+
+
+
+
+ );
+}
+
+const SpacingBackground = ({children, width = '100%'}) => {
+ return (
+
+ {children}
+
+ );
+};
+
+const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
+ return (
+
+ );
+};
+
+export default withPolarisExample(ColumnsWithSetNumberExample);
diff --git a/polaris.shopify.com/pages/examples/columns-with-varying-spacing.tsx b/polaris.shopify.com/pages/examples/columns-with-varying-spacing.tsx
index e164f28a4b6..0efdfdce794 100644
--- a/polaris.shopify.com/pages/examples/columns-with-varying-spacing.tsx
+++ b/polaris.shopify.com/pages/examples/columns-with-varying-spacing.tsx
@@ -1,21 +1,62 @@
import React from 'react';
-import {Columns} from '@shopify/polaris';
+import {Columns, Text, Inline} from '@shopify/polaris';
import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
function ColumnsWithVaryingGapExample() {
return (
-
-
- Column one
- Column two
- Column three
+
+
+
+
+
+
+
+
-
+
);
}
+const SpacingBackground = ({children, width = '100%'}) => {
+ return (
+
+ {children}
+
+ );
+};
+
+const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
+ return (
+
+ );
+};
+
export default withPolarisExample(ColumnsWithVaryingGapExample);