Common actions pattern exists
Polaris includes a pattern for common actions that standardizes recurring actions to give merchants a predictable way to complete common tasks.
Shopify Polaris · all subjects
patterns
64 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
Common actions pattern has overview and best practices variants
The common actions pattern includes two documented variants: an overview variant and a best practices variant.
Date list ordering: single dates then ranges
Single dates should be at the top of the list, followed by date ranges ordered from smallest to largest ranges.
Date list can be adapted for different use cases
A date list can be modified to serve unique situations, such as providing suggested search queries in the customer segment editor.
Date list pattern enables preset date selection
The date list pattern enables merchants to select a date or a date range from a list of preset dates. It provides suggested dates that make date picking simpler when useful dates are predictable and custom dates aren't necessary.
Date list use case: templated dates that don't need filtering
Use the date list pattern when a templated list of dates is sufficient for the merchant task and when the task does not require in-depth filtering of historical information. An example location is the Inbox app Overview.
Date list pattern component composition
The date list pattern uses the Button, OptionList, and Popover components.
Date list example implementation
const ranges = [ { title: 'No Date', alias: 'no-date', period: null, }, { title: 'Today', alias: 'today', period: { since: 'today', until: 'today', }, }, { title: 'Yesterday', alias: 'yesterday', period: { since: 'yesterday', until: 'yesterday', }, }, { title: 'Last 7 days', alias: 'last7days', period: { since: '-7d', until: '-1d', }, }, ]; const [selected, setSelected] = useState(ranges[0]); const [popoverActive, setPopoverActive] = useState(false); return ( <Popover autofocusTarget="none" preferredAlignment="left" preferInputActivator={false} preferredPosition="below" activator={ <Button onClick={() => setPopoverActive(!popoverActive)} icon={CalendarIcon} > {selected.title} </Button> } active={popoverActive} > <OptionList options={ranges.map((range) => ({ value: range.alias, label: range.title, }))} selected={selected.alias} onChange={(value) => { setSelected(ranges.find((range) => range.alias === value[0])); setPopoverActive(false); }} /> </Popover> ); This example shows a date list picker with preset options including "No Date", "Today", "Yesterday", and "Last 7 days", using a Popover containing an OptionList with a Button activator.
Date list default button state should show likely date
In the button preview, set a default date range that a merchant will most likely use.
Add action placement in selectable lists
Place add actions at the bottom of a list of selectable options. For example, when picking a collection or tag to add to a product. Keep the action visible by placing it outside of the scrollable area.
Add action placement in long lists
Place add actions in the header in long lists of resources.
Add action placement with tables
Place add actions associated with a table in the card, table, or page header. Use a secondary button when 'Add' is the main action for a card that has a standalone table or list as its content.
Add action pitfall: placing in table bottom
Do not place add actions at the bottom of a table. This risks them getting lost and can cause confusion.
Add action pitfall: intermediary modal steps
Do not include intermediary steps during the creation of a resource. Place these configuration options on the newly created page itself.
More actions definition and purpose
More actions display available or additional actions for element or item.
Copy action icon for text strings
Use the clipboard icon with a tertiary icon button for copying a string of text.
Copy action icon for links
Use the link icon with a tertiary icon button for copying deep links and URLs.
Copy action visibility on hover
Show copy actions on hover for cursor interactions.
Copy action feedback inline confirmation
Provide feedback inline using a confirmation check icon post-click or tap.
Copy action feedback in action lists
Use a confirmation 'copied to clipboard' toast message when the action is within an action list.
Delete action definition and purpose
Delete destroys an item or object and completely erases data from the system.
Delete action in action lists
Use the delete icon with a destructive item in an action list.
Delete action placement in action lists
Always place delete actions at the bottom of an action list.
Delete action icon for lists
Use the delete icon for delete actions in lists.
Delete action inline placement
Place list item delete actions inline to the right. Default to a tertiary button with the delete icon.
Delete action visibility on hover
Display list item delete actions on hover when using a cursor.
Edit action definition and purpose
Edit actions allow merchants to make changes to a piece of content or object that already exists in the system.
Edit action use cases
Use edit for modifying, updating or managing an item or object.
Edit action default icon
Default to the edit icon with a tertiary icon button.
Edit action caution: button density
Avoid using too many buttons with filled or shaped containers in close proximity to each other, as they will make the interface feel cluttered and confusing.
Copy action definition and purpose
Copy duplicates selected content and stores it temporarily in the merchant's clipboard.
More actions icon
Use the menu horizontal icon to indicate available or more actions for an item.
More actions button style
Use a secondary or tertiary icon button for more actions.
Delete action pitfall: overusing critical styling
Do not overuse critical styled buttons within a single view as it can dilute the meaning and importance of the action.
Delete action pitfall: pairing with other primary buttons
Do not pair primary critical buttons with other button variants and tones that look jarring and create visual competition between elements.
Add action definition and purpose
Add inserts existing or new objects, items, or data into the UI. For example, adding an item to a list or adding an element into a layout.
Add action default icon
Default to the circle plus icon for add actions.
Add action icon for secondary and primary buttons
Use the plus icon in secondary and primary button variants. The plus icon supports the action while balancing the weight of the filled shaped element with the rest of the UI.
Add action placement in short lists
Place add actions at the bottom of a list unless the list will likely be long. For example, a table or list of selected resources.
More actions pitfall: grouping in card header
Do not group actions in the card header by default. Instead, consider alternative solutions that place actions in context or appear within a given flow or task as needed.
Pin action definition and purpose
Pin sticks an object to an easily accessible location within the UI. Pinning allows merchants to keep important items available to quickly access later.
Pin action icon
Use the pin icon with a tertiary icon button to communicate an item can be pinned.
Pin action pinned state icon
Use the pin filled icon on an item to show that it has been pinned.
Pin action placement for pinned items
Placed pinned objects together to add clarity to the relationship between items.
Pin action unpinning usability
Make it easy to unpin an item.
Remove action definition and purpose
Remove removes an item from a list or breaks the relationship between objects. When an object is removed, it is taken out of a given context without deleting it from the system. For example, if a product is removed from a collection, it still exists and can be easily added back.
Remove action icon
Use the x icon with a tertiary icon button for remove actions.
Remove action visibility on hover
Show remove actions on hover when the merchant is using a cursor to navigate.
Remove action pitfall: delete icon
Do not use the delete icon for remove actions.
New features pattern has default variant
The new features pattern includes at least one variant called 'default' defined in variants/default.mdx.
New features pattern exists
Polaris includes a pattern for highlighting new features to merchants to help them discover new and impactful features.
Resource details layout related to Resource list component
The Resource details layout pattern relates to the Resource list component, which defines the meaning of 'resources' in this context.
Resource details layout relates to Layout design guidelines
The Resource details layout pattern is connected to the Layout section of Shopify app design guidelines for additional context on layout principles.
Resource details layout pattern purpose
The Resource details layout pattern lets merchants create, view, and edit resource objects.
Resource list component for resource definitions
Refer to the Resource list component page to learn about the meaning of "resources".
Resource detail layout complements resource index layout
The Resource detail layout pattern is a complement to the resource index layout pattern.
Resource index layout pattern
The resource index layout pattern helps merchants organize and take action on resource objects.
Empty state component for empty resource index
Use the Empty state component when the resource index is empty.
Single date pattern can be duplicated for date ranges
The single date pattern can be duplicated to allow merchants to add an end date or time, creating a date range input with start and end date fields.
Single date pattern purpose
The single date pattern enables merchants to type a specific date or pick it from a calendar. It combines a text input field with a single-month calendar view.