article-component-template.md

[Canonical Component Name] (Commonly used Component Name)

example Android Buttons title:

Buttons (Material Buttons)

Add a concise (1-2 sentence) description of the component here starting with the one-line definition from the design/guidance page. The corresponding design document should have a full description.

Add a link to the corresponding design page that the component (helps) implement.

For example:

Buttons allow users to take actions and make choices with a single tap. Buttons can be customized to meet your style requirements.

Buttons

[Component variants]

When to use

If there are component variants, list them here and link to the local anchor link for its section.

• Text button
• Outlined button
• Contained button
• Toggle button

Insert any related graphics: show instead of say.

example images from Buttons:

Using [Component Name ]

Use 1-2 sentences to describe how the component is used. Provide images of its relative position, if relevant. Use collapsible tags for examples that require more than a page of text.

If there are any instructions on using the component that applies to all component variants, include them here.

For example, for the iOS buttons component:

Install mcd-button

Before using the MDCButtons component to implement its variants you must install MCDButtons. In your source files import the component, and then apply your theme:

1. Install MDCButtons

   • Use CocoaPods to install MDCButtons
     1. Add the following to your Podfile:

     pod MaterialComponents/Buttons

     1. Run the installer:

     pod install

2. Import MDCButtons and MDC buttons theming and initialize MDCButtons using alloc/init. Initialize your theme before applying it to your button.

   Note For more information about themes, go to the Theming page for iOS.

   Swift

   import MaterialComponents.MaterialButtons
   import MaterialComponents.MaterialButtons_Theming
   /*...*/
   let <local theme name> = <theme name>
   let button = MDCButton()

   Objective-C

   #import "MaterialButtons.h"
   #import <MaterialComponentsBeta/MaterialButtons+Theming.h>
   /*...*/
   <theme name> *<local theme name> = [[<theme name> alloc] init];
   MDCButton *button = [[MDCButton alloc] init];

3. Apply accessibility settings To help make your buttons usable to as many users as possible:

   • Set an appropriate accessibilityLabel value if your button does not have a title or only has an icon. Objective-C

     button.accessibilityLabel = @"Create";

     Swift

     button.accessibilityLabel = "Create"

Related APIs

If relevant, insert all the related component code, and link to its API.

For example, from the iOS Button component:

Class: MCDRaisedButton

Interface Class

@interface MDCButton : UIButton <MDCElevatable, MDCElevationOverriding>

Properties

inkStyle

This is a description of the inkStyle property for iOS.

inkColor

This is a description of the inkColor property for iOS.

[Component section]

Divide the component API into its variants, preferably as described in the [material.io/components] pages.

For example buttons is divided into the following 3rd tier (### header) sections based on its variants:

• Text button
• Outlined button
• Contained button
• Toggle button

Whereas cards is divided into:

• Behavior
• Actions
• Card collections

Each section should have a 3rd tier header. Add 1-2 sentences from the material.io website that describes when and how to use the component. Within each section, there should be a table that contains:

• an image of the section topic
• a general description
• classes, parameters, enums related to the section
• links to the applicable API(s) if there are any specific to the section.

If possible, each section should have its own example(s) with code snippets/settings relevant to the section and an image showing what the code could generate. All code samples should be self-contained easy to cut and paste into a user's existing code and be expected to work.

Example: Android Button

Android text button

Text buttons are typically used for less-pronounced actions, including those located: * In dialogs * In cards In cards, text buttons help maintain an emphasis on card content.

Attribute	Attribute value	Element description
android:id	"@+id/material_text_button"
style	"@style/Widget.MaterialComponents.Button.TextButton"
android:layout_width	"wrap_content"
android: layout_height	"wrap_content"
android:text	"@string/text_button_label_enabled"

Android text button example

 <com.google.android.material.button.MaterialButton
   android:id="@+id/material_text_button"
   style="@style/Widget.MaterialComponents.Button.TextButton"
   android:layout_width="wrap_content"
   android:layout_height="wrap_content"
   android:text="@string/text_button_label_enabled"/>

...

Example: [Describe a way to use the Component]

• Provide an example scenario of how the component might be used. Preferably, chose an example that implements something that resembles one of the design examples for the related [material.io/components] page, such as an extended floating action button
  • What functions/objects/methods does it use?
  • How does the example use the objects/functions?
  • Are there any special settings/options used in this example, and why?
• Provide an image of what the example could produce. Mention any themes/settings used. Ideally each example will have an image or video showing a render of code example.

Click to View Examples without Steps

Describe the example and its components, including specific settings and instructions.

Example: Add a contained (filled) and elevated button

The following code adds a contained and elevated button to your app. Your theme's colorPrimary is the default background color and your theme's colorOnPrimary is the default text color.

 <com.google.android.material.button.MaterialButton
   android:id="@+id/material_button"
   android:layout_width="wrap_content"
   android:layout_height="wrap_content"
   android:text="@string/button_label_enabled"/>

Example: Add a contained (filled) and unelevated button

The following code adds a contained and unelevated button. Your theme's colorPrimary is the default background color and your theme's colorOnPrimary is the default text color.

  <com.google.android.material.button.MaterialButton
    android:id="@+id/disabled_material_button"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:enabled="false"
    android:text="@string/button_label_disabled"/>

Click to View Examples with Steps

If the example entails multiple steps, use a numbered list for each step. Break out any installation/importation steps into its own list.

List the steps to use the component. Include any installation/importation instructions in a separate list.

Add a themed text button

Follow the steps below to add a text button in your iOS application:

1. Add the following to your Podfile:

pod 'MaterialComponents/Buttons'

2. Run the install command:

 pod install

3. In your source file, you will need to:
   • import MaterialButtons

       import MaterialComponents.MaterialButtons

   • import MaterialButtons_Theming

     import MaterialComponents.MaterialButtons_Theming

   • initialize the button

     let button = MDCButton()

   • apply a theme to the text button

     button.applyTextTheme(withScheme: containerScheme)