@shopify/polaris

--- name: Layout category: Structure keywords: - one column - two column - three column - column - annotated - page - column layouts - containers - full width containers - secondary sections - setting page - grouped sections - annotated sections --- # Layout The layout component is used to create the main layout on a page. Layouts sections come in three main configurations: one-column, two-column, and annotated. One and two column layouts can be combined in the same page. Annotated layouts should be used on their own and only on settings pages. --- ## Best practices The layout component should: - Use sections with white backgrounds for primary content and sections with grey backgrounds for secondary content that is less important - Center cards on the background when there is no secondary card on the page to stop the content from becoming too wide - Group similar concepts and actions together in cards - Separate different cards using a full-width divider - Structure primary/secondary, two-column layouts so the primary ⅔ section is used for main information and the secondary ⅓ section is used for information that might not be used as often but remains helpful for context or secondary tasks - Use equal-width layouts with two or more columns when each layout section has the same importance --- ## Content guidelines The content that appears in the layout component comes from cards and annotated sections. ### Cards Content from cards should follow the content guidelines for [cards](https://polaris.shopify.com/components/structure/card#section-content-guidelines). ### Annotated section titles Annotated section titles should follow the content guidelines for [headings and subheadings](https://polaris.shopify.com/content/actionable-language#section-headings-and-subheadings). ### Annotated section descriptions Annotated section descriptions should: - Be used if the explanation or purpose of the associated cards isn’t clear - Provide instructions for any choices merchants need to make, or explain the purpose of the section - Be short, no more than 1–3 sentences - Direct merchants to more content in the Help Center with “Learn more” links - Not repeat the section title - Use complete sentences and regular punctuation --- ## Examples ### One-column layout Use to have a single section on its own in a full-width container. Use for simple pages and as a container for banners and other full-width content. ```jsx <Layout> <Layout.Section> <Card title="Online store dashboard" sectioned> <p>View a summary of your online store’s performance.</p> </Card> </Layout.Section> </Layout> ``` ### Two columns with primary and secondary widths Use to follow a normal section with a secondary section to create a 2/3 + 1/3 layout on detail pages (such as individual product or order pages). Can also be used on any page that needs to structure a lot of content. This layout stacks the columns on small screens. ```jsx <Layout> <Layout.Section> <Card title="Order details" sectioned> <p>View a summary of your order.</p> </Card> </Layout.Section> <Layout.Section secondary> <Card title="Tags" sectioned> <p>Add tags to your order.</p> </Card> </Layout.Section> </Layout> ``` ### Two columns with equal width Use to create a ½ + ½ layout. Can be used to display content of equal importance. This layout will stack the columns on small screens. ```jsx <Layout> <Layout.Section oneHalf> <Card title="Florida" actions={[{content: 'Manage'}]}> <Card.Section> <TextStyle variation="subdued">455 units available</TextStyle> </Card.Section> <Card.Section title="Items"> <ResourceList resourceName={{singular: 'product', plural: 'products'}} items={[ { id: 341, url: 'produdcts/341', name: 'Black & orange scarf', sku: '9234194023', quantity: '254', media: ( <Thumbnail source="https://burst.shopifycdn.com/photos/black-orange-stripes_373x@2x.jpg" alt="Black orange scarf" /> ), }, { id: 256, url: 'produdcts/256', name: 'Tucan scarf', sku: '9234194010', quantity: '201', media: ( <Thumbnail source="https://burst.shopifycdn.com/photos/tucan-scarf_373x@2x.jpg" alt="Tucan scarf" /> ), }, ]} renderItem={(item) => { const {id, url, name, sku, media, quantity} = item; return ( <ResourceList.Item id={id} url={url} media={media} accessibilityLabel={`View details for ${name}`} > <h3> <TextStyle variation="strong">{name}</TextStyle> </h3> <div>SKU: {sku}</div> <div>{quantity} available</div> </ResourceList.Item> ); }} /> </Card.Section> </Card> </Layout.Section> <Layout.Section oneHalf> <Card title="Nevada" actions={[{content: 'Manage'}]}> <Card.Section> <TextStyle variation="subdued">301 units available</TextStyle> </Card.Section> <Card.Section title="Items"> <ResourceList resourceName={{singular: 'product', plural: 'products'}} items={[ { id: 342, url: 'produdcts/342', name: 'Black & orange scarf', sku: '9234194023', quantity: '100', media: ( <Thumbnail source="https://burst.shopifycdn.com/photos/black-orange-stripes_373x@2x.jpg" alt="Black orange scarf" /> ), }, { id: 257, url: 'produdcts/257', name: 'Tucan scarf', sku: '9234194010', quantity: '201', media: ( <Thumbnail source="https://burst.shopifycdn.com/photos/tucan-scarf_373x@2x.jpg" alt="Tucan scarf" /> ), }, ]} renderItem={(item) => { const {id, url, name, sku, media, quantity} = item; return ( <ResourceList.Item id={id} url={url} media={media} accessibilityLabel={`View details for ${name}`} > <h3> <TextStyle variation="strong">{name}</TextStyle> </h3> <div>SKU: {sku}</div> <div>{quantity} available</div> </ResourceList.Item> ); }} /> </Card.Section> </Card> </Layout.Section> </Layout> ``` ### Three columns with equal width Use to create a ⅓ + ⅓ + ⅓ layout. Can be used to display content of equal importance. This layout will stack the columns on small screens. ```jsx <Layout> <Layout.Section oneThird> <Card title="Florida" actions={[{content: 'Manage'}]}> <Card.Section> <TextStyle variation="subdued">455 units available</TextStyle> </Card.Section> <Card.Section title="Items"> <ResourceList resourceName={{singular: 'product', plural: 'products'}} items={[ { id: 343, url: 'produdcts/343', name: 'Black & orange scarf', sku: '9234194023', quantity: '254', media: ( <Thumbnail source="https://burst.shopifycdn.com/photos/black-orange-stripes_373x@2x.jpg" alt="Black orange scarf" /> ), }, { id: 258, url: 'produdcts/258', name: 'Tucan scarf', sku: '9234194010', quantity: '201', media: ( <Thumbnail source="https://burst.shopifycdn.com/photos/tucan-scarf_373x@2x.jpg" alt="Tucan scarf" /> ), }, ]} renderItem={(item) => { const {id, url, name, sku, media, quantity} = item; return ( <ResourceList.Item id={id} url={url} media={media} accessibilityLabel={`View details for ${name}`} > <h3> <TextStyle variation="strong">{name}</TextStyle> </h3> <div>SKU: {sku}</div> <div>{quantity} available</div> </ResourceList.Item> ); }} /> </Card.Section> </Card> </Layout.Section> <Layout.Section oneThird> <Card title="Nevada" actions={[{content: 'Manage'}]}> <Card.Section> <TextStyle variation="subdued">301 units available</TextStyle> </Card.Section> <Card.Section title="Items"> <ResourceList resourceName={{singular: 'product', plural: 'products'}} items={[ { id: 344, url: 'produdcts/344', name: 'Black & orange scarf', sku: '9234194023', quantity: '100', media: ( <Thumbnail source="https://burst.shopifycdn.com/photos/black-orange-stripes_373x@2x.jpg" alt="Black orange scarf" /> ), }, { id: 259, url: 'produdcts/259', name: 'Tucan scarf', sku: '9234194010', quantity: '201', media: ( <Thumbnail source="https://burst.shopifycdn.com/photos/tucan-scarf_373x@2x.jpg" alt="Tucan scarf" /> ), }, ]} renderItem={(item) => { const {id, url, name, sku, media, quantity} = item; return ( <ResourceList.Item id={id} url={url} media={media} accessibilityLabel={`View details for ${name}`} > <h3> <TextStyle variation="strong">{name}</TextStyle> </h3> <div>SKU: {sku}</div> <div>{quantity} available</div> </ResourceList.Item> ); }} /> </Card.Section> </Card> </Layout.Section> <Layout.Section oneThird> <Card title="Minneapolis" actions={[{content: 'Manage'}]}> <Card.Section> <TextStyle variation="subdued">1931 units available</TextStyle> </Card.Section> <Card.Section title="Items"> <ResourceList resourceName={{singular: 'product', plural: 'products'}} items={[ { id: 345, url: 'produdcts/345', name: 'Black & orange scarf', sku: '9234194023', quantity: '1230', media: ( <Thumbnail source="https://burst.shopifycdn.com/photos/black-orange-stripes_373x@2x.jpg" alt="Black orange scarf" /> ), }, { id: 260, url: 'produdcts/260', name: 'Tucan scarf', sku: '9234194010', quantity: '701', media: ( <Thumbnail source="https://burst.shopifycdn.com/photos/tucan-scarf_373x@2x.jpg" alt="Tucan scarf" /> ), }, ]} renderItem={(item) => { const {id, url, name, sku, media, quantity} = item; return ( <ResourceList.Item id={id} url={url} media={media} accessibilityLabel={`View details for ${name}`} > <h3> <TextStyle variation="strong">{name}</TextStyle> </h3> <div>SKU: {sku}</div> <div>{quantity} available</div> </ResourceList.Item> ); }} /> </Card.Section> </Card> </Layout.Section> </Layout> ``` ### Annotated layout Use for settings pages. When settings are grouped thematically in annotated sections, the title and description on each section helps merchants quickly find the setting they’re looking for. ```jsx <Layout> <Layout.AnnotatedSection title="Store details" description="Shopify and your customers will use this information to contact you." > <Card sectioned> <FormLayout> <TextField label="Store name" onChange={() => {}} /> <TextField type="email" label="Account email" onChange={() => {}} /> </FormLayout> </Card> </Layout.AnnotatedSection> </Layout> ``` --- ## Related components - To visually group content in a layout section, [use the card component](https://polaris.shopify.com/components/structure/card) - To lay out a set of smaller components in a row, [use the stack component](https://polaris.shopify.com/components/structure/stack) - To lay out form fields, [use the form layout component](https://polaris.shopify.com/components/forms/form-layout)