New Component: Card

[micahgodbolt]

Component Details

A Card is a surface to display content and actions about a single topic. It acts as a container for actionable information like text, images and icons.

A Card should abstract styling properties and utilize them in tandem with theme variables. Some of the properties to abstract are:

• Paddings
• Widths
• Heights
• Shadowing
• Borders
• Colors

Considerations and Design Decisions

There are a couple of things to consider and discuss regarding the implementation of a Card component. Some of these considerations are outlined below:

• The introduction of a compact Card, which places the items in a row to use less screen space.
• A Card is responsive to screen size changes, but only within a limited range. A default minimum and maximum width are provided, with the ability to override this for custom scenarios.
• Fixed height in individual scenarios vs stretching height in multiple card scenarios.
• The default behavior is defined for margins and padding, and the component provides an easy way to opt out of this default behavior.
• Hovering styling indicates a Card is clickable.

Component Documentation

Imports

The Stack component is used to generate the Card container.

Exports/ Component Breakdown

Both the Card and CardItem components are exported, as well as the Card and CardItem properties defined in Card.types and CardItem.types respectively.

Intended Package

The component lives in a newly created react-cards package.

Code mockup/example

Regular Card Example

const styles = mergeStyleSets({
   siteText: {
      color: '#025F52',
      fontSize: 12,
      fontWeight: FontWeights.semibold
   },
   descriptionText: {
      color: '#333333',
      fontSize: 14,
      fontWeight: FontWeights.regular
   },
   helpfulText: {
      color: '#333333',
      fontSize: 12,
      fontWeight: FontWeights.regular
   },
   icon: {
      color: '#0078D4',
      fontSize: 16,
      fontWeight: FontWeights.regular
   }
});

const tokens = {
   sectionStack: {
      childrenGap: 30
   },
   cardFooterStack: {
      childrenGap: 16
   }
};

<Card onClick={alertClicked}>
   <Persona text="Kevin Jameson" secondaryText="Feb 2, 2019" />
   <Card.Item tokens={{ margin: '0 -13px' }}>
      <Image src="https://placehold.it/286x144" width="100%" />
   </Card.Item>
   <Text className={styles.siteText}>Contoso</Text>
   <Text className={styles.descriptionText}>Contoso Denver expansion design marketing hero guidelines</Text>
   <Text className={styles.helpfulText}>Is this recommendation helpful?</Text>
   <Card.Item>
      <Stack horizontal tokens={tokens.cardFooterStack} padding="12px 0 0" styles={{ root: { borderTop: '1px solid #F3F2F1' } }}>
         <Icon iconName="RedEye" className={styles.icon} />
         <Icon iconName="SingleBookmark" className={styles.icon} />
         <Stack.Item grow={1}>
            <span />
         </Stack.Item>
         <Icon iconName="MoreVertical" className={styles.icon} />
      </Stack>
   </Card.Item>
</Card>

Compact Card Example

const styles = mergeStyleSets({
   siteText: {
      color: '#025F52',
      fontSize: 12,
      fontWeight: FontWeights.semibold
   },
   descriptionText: {
      color: '#333333',
      fontSize: 14,
      fontWeight: FontWeights.regular
   },
   helpfulText: {
      color: '#333333',
      fontSize: 12,
      fontWeight: FontWeights.regular
   },
   icon: {
      color: '#0078D4',
      fontSize: 16,
      fontWeight: FontWeights.regular
   }
});

<Card compact={true} onClick={alertClicked}>
   <Card.Item tokens={{ margin: '-12px 0 -12px -12px' }}>
      <Image src="https://placehold.it/180x135" />
   </Card.Item>
   <Stack gap={12}>
      <Text className={styles.siteText}>Contoso</Text>
      <Text className={styles.descriptionText}>Contoso Denver expansion design marketing hero guidelines</Text>
      <Text className={styles.helpfulText}>Is this recommendation helpful?</Text>
   </Stack>
   <Stack gap={16} padding="0 0 0 12px" styles={{ root: { borderLeft: '1px solid #F3F2F1' } }}>
      <Icon iconName="RedEye" className={styles.icon} />
      <Icon iconName="SingleBookmark" className={styles.icon} />
      <Stack.Item grow={1}>
         <span />
      </Stack.Item>
      <Icon iconName="MoreVertical" className={styles.icon} />
   </Stack>
</Card>

Card Types

ICardSlots

Name	Type	Description
root	IStackSlot	Defines root slot of the component for managing the layout of the Card.

ICardProps

Name	Type	DefaultValue	Description
compact	boolean	false	Defines whether to render a regular or a compact Card.
onClick	(ev: React.MouseEvent<HTMLElement>) => void		Defines a callback that is called when the Card is clicked.

ICardTokens

Name	Type
boxShadow	string
boxShadowHovered	string
childrenGap	number | string
height	number | string
maxWidth	number | string
minHeight	number | string
minWidth	number | string
padding	number | string
width	number | string

Component Ownership

@khmakoto who will be creating the Card component.

Deadlines

The initial basic Card container is expected to be finalized by April 2019, with further variants that may come in a foreseeable future.

Related PRs

• Card: Adding first prototype for Basic Card component #7954 - Adding first prototype of Card component into experiments package
• Card: Exporting Card from experiments. #8129 - Exporting Card from experiments package
• Creating react-cards package #8200 - Creating react-cards package and migrating Card component into it
• Publishing react-cards package. #8239 - Publishing react-cards package
• Card: Improving styling and adding compact Card styling and examples #8247 - Improving styling and adding compact Card styling and examples
• Card: Updating examples #8590 - Updating examples
• Card: Supporting High Contrast mode #8591 - Supporting High Contrast mode
• Adding documentation for token docs in Button, Card and Stack #8774 - Adding documentation for token docs in Button, Card and Stack
• Card: Changing import of Stack to import from office-ui-fabric-react/lib/Stack given partner requests #8784 - Changing import of Stack to import from office-ui-fabric-react/lib/Stack given partner requests
• Card: Improving CardItem and adding CardSection to allow Card children to fill the Card's margins #8813 - Improving CardItem and adding CardSection to allow Card children to fill the Card's margins
• Card: Adding vr-tests #9042 - Adding vr-tests
• Card: Making elevation themable by using the effects from theme instead of directly referencing Depths #9472 - Making elevation themable by using the effects from theme instead of directly referencing Depths
• Card: Importing from office-ui-fabric-react directly instead of from office-ui-fabric-react/lib/... #9652 - Importing from office-ui-fabric-react directly instead of from office-ui-fabric-react/lib/...
• Card: Showing examples on demo page and website #10071 - Showing examples on demo page and website

Steps

• Themable (Component.base/Component.styles)
• Unit tests (Card: Improving CardItem and adding CardSection to allow Card children to fill the Card's margins #8813)
• Visual tests (Card: Adding vr-tests #9042)
• Documentation and examples
• Keyboard Accessible
• High Constrast Support (Card: Supporting High Contrast mode #8591)
• Accessibility Insights for Web Fast Pass
• RTL Support
• Design Review
• API review
• Public Preview
• Ready for Publishing

[dzearing]

This isn't a P1. But it's a feature we need. Let's prioritize

[micahgodbolt]

Should Priority tags only be used for bugs?

[kheide]

Do you have an ETA for this (and the Tile component) or should we find replacements in the interim?

[micahgodbolt]

@kheide This hasn't been started yet, just a known gap in our component coverage. We're hoping to work on it in the coming month or so.

[kheide]

Fantastic. Thanks!

Also I just discovered the Chiclet component which sort of also helps.

[micahgodbolt]

@mikewheaton making sure you're aware of this issue for tracking work on card.

[danielgwilson]

+1

[khmakoto]

@tenzin-copart just updated the description to better reflect current deadlines, but the short answer is that yes, there is a basic Card component that we are trying to ship by March 2019.

Work on this should start speeding up beginning next week and all related PRs will be linked to this issue.

[tenzin-copart]

@khmakoto - Is this component ready now?

[khmakoto]

Hi @tenzin-copart we have a prototype in its own @uifabric/react-cards package if you want to try out today and it's close to be finished. We hosted an API review last Friday which surface some extra work we need to do but you can play with it for now if you're interested in checking it out.

[Rtoribiog]

hello @khmakoto any update on this ? Thanks

[khmakoto]

Hi @Rtoribiog, the Card component is in a state where we deem it ready to be promoted to our official package, but we've been having some difficulties doing that because of the work we're doing in #9645. In the meantime, if you want to try the production-ready component, you can import it from the @uifabric/react-cards package.

[Sentri]

Since #9645 is on hold, are there any new plans now to introduce this into the main package?

[khmakoto]

Hi @Sentri, I don't think there's any effort to bring it into the main package right now since #9645 is on hold but you can use the @uifabric/react-cards package. The API is basically finished at this point so if we ever decide to move it to the main package it shouldn't break your project.

[vitaliyKorzhenko]

@Sentri How I can change styles if I clicked on card? I need use selector?

[khmakoto]

@vitaliyKorzhenko yes, you do need to use a selector in that case.

[beeisabelm]

@khmakoto the compliance issue blocks us from using experimental API. What is the blocker or constraint that needs to be done in order to ship it? Thanks.

[jeffersoneagley]

Does Card respond to a Customizer yet? I tried setting some styles, and it didn't seem to change anything. I could be doing it wrong 🤷‍♂️

export const makeScopedSettings = theme => ({
// ...
  Card: {
    styles: cardStyles(theme),
  },
  CardItem: {
    styles: cardStyles(theme),
  },
//.......... etc

For now, I'm overriding the .ms-Card class as a workaround.

[jeffersoneagley]

Any updates on the cards getting merged in?

[khmakoto]

@beeisabelm @jeffersoneagley we're currently in the process of revamping our components from many angles: bundle size, styling, API interface, etc. Card will be part of these components and that will hopefully remove any barriers for merging. We'll keep you updated on the process.

[jeffersoneagley]

I noticed they were just marked as deprecated. Should we be moving to a Card from elsewhere in the library then? I've got people asking now that they're seeing a strikethrough in their VSCode.

[khmakoto]

@jeffersoneagley like I mentioned in my comment above, we're currently in the process of revamping our components from many angles. I don't have an ETA yet for when Card will be moved to this new model but we'll keep you updated.

[jeffersoneagley]

Right, but it was just recently marked deprecated, and that's causing compliance issues for some people now. I don't want to go reinvent the wheel on it, but deprecated kind of implies there's something else I should be using.

[Pixelatex]

So I was very confused why Card is not available yet in fluentui... many of your components seem to use some form of a card like the DetailsList. Please can we get a basic Card version merged?

[msft-fluent-ui-bot]

Because this issue has not had activity for over 150 days, we're automatically closing it for house-keeping purposes.

Still require assistance? Please, create a new issue with up-to date details.

[jeffersoneagley]

No bot, this is still an open question.

[khmakoto]

We're working on a new version of the Card component, please look at #19336 for an epic tracking this work.