Button

A button allows a users to take actions, and make choices, with a single press.

Install	`yarn add @diallink-corp/convergo-react-button`
Version	4.1.2
Usage	import {Button} from '@diallink-corp/convergo-react-button'

Contained Buttons

Contained buttons are giving an action a high-emphasis and are distinguished by their fill. They contain actions that are primary to the application.

<Button variant='contained' color='primary'>Primary</Button>
<Button variant='contained' color='secondary'>Secondary</Button>
<Button variant='contained' color='danger'>Danger</Button>
<Button variant='contained' isDisabled>Disabled</Button>

<Button variant="contained" color="primary">
  Primary
</Button>
<Button variant="contained" color="secondary">
  Secondary
</Button>
<Button variant="contained" color="danger">Danger</Button>
<Button variant="contained" isDisabled>Disabled</Button>

<Button
  variant="contained"
  color="primary"
>
  Primary
</Button>
<Button
  variant="contained"
  color="secondary"
>
  Secondary
</Button>
<Button
  variant="contained"
  color="danger"
>
  Danger
</Button>
<Button
  variant="contained"
  isDisabled
>
  Disabled
</Button>

Outlined Buttons

Outlined buttons are giving an action a medium-emphasis and are distinguished by their transparent background and colored outline. They contain actions that are important, but aren’t the primary action in the app.

<Button variant='outlined' color='primary'>Primary</Button>
<Button variant='outlined' color='secondary'>Secondary</Button>
<Button variant='outlined' color='danger'>Danger</Button>
<Button variant='outlined' isDisabled>Disabled</Button>

<Button variant="outlined" color="primary">
  Primary
</Button>
<Button variant="outlined" color="secondary">
  Secondary
</Button>
<Button variant="outlined" color="danger">Danger</Button>
<Button variant="outlined" isDisabled>Disabled</Button>

<Button
  variant="outlined"
  color="primary"
>
  Primary
</Button>
<Button
  variant="outlined"
  color="secondary"
>
  Secondary
</Button>
<Button
  variant="outlined"
  color="danger"
>
  Danger
</Button>
<Button
  variant="outlined"
  isDisabled
>
  Disabled
</Button>

Text Buttons

Text buttons are giving an action a low-emphasis and are distinguished by them having no background or outline. They contain actions that are of low importance in the app.

<Button variant='text' color='primary'>Primary</Button>
<Button variant='text' color='secondary'>Secondary</Button>
<Button variant='text' color='danger'>Danger</Button>
<Button variant='text' isDisabled>Disabled</Button>

<Button variant='text' color='primary'>Primary</Button>
<Button variant='text' color='secondary'>Secondary</Button>
<Button variant='text' color='danger'>Danger</Button>
<Button variant='text' isDisabled>Disabled</Button>

<Button
  variant="text"
  color="primary"
>
  Primary
</Button>
<Button
  variant="text"
  color="secondary"
>
  Secondary
</Button>
<Button
  variant="text"
  color="danger"
>
  Danger
</Button>
<Button
  variant="text"
  isDisabled
>
  Disabled
</Button>

Sizes

The button component comes in three different sizes: small, medium and large. Typically the medium size is recommended, however in certain scenarios changing the emphasis of the button can make sense. If you run into such a situation, you can do so by increasing or decreasing the buttons size.

<Button size='small'>Small</Button>
<Button size='medium'>Medium</Button>
<Button size='large'>Large</Button>

<Button size='small'>Small</Button>
<Button size='medium'>Medium</Button>
<Button size='large'>Large</Button>

<Button size="small">
  Small
</Button>
<Button size="medium">
  Medium
</Button>
<Button size="large">
  Large
</Button>

Events

The button component allows the user to interact with it via touch, keyboard or mouse. To handle all of these, we expose an onPress prop. You can also alternatively pass an onClick prop, however this will omit the keyboard support. As such, the onPress prop is favored over the onClick prop for accessibility.

function Example() {
  const [pressCount, setPressCount] = useState(0);

  const handlePress = () => {
    setPressCount((prevPressCount) => prevPressCount + 1);
  };

  return (
    <Button onPress={handlePress}>{pressCount} Presses</Button>
  );
}

function Example() {
  const [pressCount, setPressCount] = useState(0);

  const handlePress = () => {
    setPressCount((prevPressCount) => prevPressCount + 1);
  };

  return (
    <Button onPress={handlePress}>
      {pressCount} Presses
    </Button>
  );
}

function Example() {
  const [
    pressCount,
    setPressCount
  ] = useState(0);

  const handlePress =
    () => {
      setPressCount((
        prevPressCount
      ) =>
        prevPressCount +
        1
      );
    };

  return (
    <Button
      onPress={handlePress}
    >
      {pressCount}{' '}
      Presses
    </Button>
  );
}

Loading State

When a button executes an action that does not finish instantly, such as an asynchronous API call, we need to inform the user that they should wait. To do this, you can provide an isLoading prop to the button, which will replace the buttons content and display a spinner. This isLoading prop should be set to false, as soon as the operation successfully completes.

function Example() {
  const [isLoading, setLoading] = useState(false);

  const handlePress = () => {
    setLoading(true);

    setTimeout(() => {
      setLoading(false);
    }, 2000);
  };

  return (
    <Button isLoading={isLoading} onPress={handlePress}>
      Press me
    </Button>
  );
}

function Example() {
  const [isLoading, setLoading] = useState(false);

  const handlePress = () => {
    setLoading(true);

    setTimeout(() => {
      setLoading(false);
    }, 2000);
  };

  return (
    <Button isLoading={isLoading} onPress={handlePress}>
      Press me
    </Button>
  );
}

function Example() {
  const [
    isLoading,
    setLoading
  ] = useState(false);

  const handlePress =
    () => {
      setLoading(true);

      setTimeout(() => {
        setLoading(
          false
        );
      }, 2000);
    };

  return (
    <Button
      isLoading={isLoading}
      onPress={handlePress}
    >
      Press me
    </Button>
  );
}

Icons

You can optionally add an icon to the button component. This position of the icon can be adjusted via the iconAlign prop. If there are no children, such as a textual label, in the button, the alignment will be ignored to center the icon properly.

<Button
  size="small"
  iconName="PhoneIcon"
  iconVariant="solid"
  iconAlignment="start"
>
  Create user
</Button>
<Button
  size="small"
  iconName="PhoneIcon"
  iconVariant="solid"
  aria-label="Create user"
/>
<Button
  size="small"
  iconName="PhoneIcon"
  iconVariant="solid"
  iconAlignment="end"
>
  Create user
</Button>

<Button
  size="small"
  iconName="PhoneIcon"
  iconVariant="solid"
  iconAlignment="start"
>
  Create user
</Button>
<Button
  size="small"
  iconName="PhoneIcon"
  iconVariant="solid"
  aria-label="Create user"
/>
<Button
  size="small"
  iconName="PhoneIcon"
  iconVariant="solid"
  iconAlignment="end"
>
  Create user
</Button>

<Button
  size="small"
  iconName="PhoneIcon"
  iconVariant="solid"
  iconAlignment="start"
>
  Create user
</Button>
<Button
  size="small"
  iconName="PhoneIcon"
  iconVariant="solid"
  aria-label="Create user"
/>
<Button
  size="small"
  iconName="PhoneIcon"
  iconVariant="solid"
  iconAlignment="end"
>
  Create user
</Button>

<Button
  size="medium"
  iconName="PhoneIcon"
  iconVariant="solid"
  iconAlignment="start"
>
  Create user
</Button>
<Button
  size="medium"
  iconName="PhoneIcon"
  iconVariant="solid"
  aria-label="Create user"
/>
<Button
  size="medium"
  iconName="PhoneIcon"
  iconVariant="solid"
  iconAlignment="end"
>
  Create user
</Button>

<Button
  size="medium"
  iconName="PhoneIcon"
  iconVariant="solid"
  iconAlignment="start"
>
  Create user
</Button>
<Button
  size="medium"
  iconName="PhoneIcon"
  iconVariant="solid"
  aria-label="Create user"
/>
<Button
  size="medium"
  iconName="PhoneIcon"
  iconVariant="solid"
  iconAlignment="end"
>
  Create user
</Button>

<Button
  size="medium"
  iconName="PhoneIcon"
  iconVariant="solid"
  iconAlignment="start"
>
  Create user
</Button>
<Button
  size="medium"
  iconName="PhoneIcon"
  iconVariant="solid"
  aria-label="Create user"
/>
<Button
  size="medium"
  iconName="PhoneIcon"
  iconVariant="solid"
  iconAlignment="end"
>
  Create user
</Button>

<Button
  size="large"
  iconName="PhoneIcon"
  iconVariant="solid"
  iconAlignment="start"
>
  Create user
</Button>
<Button
  size="large"
  iconName="PhoneIcon"
  iconVariant="solid"
  aria-label="Create user"
/>
<Button
  size="large"
  iconName="PhoneIcon"
  iconVariant="solid"
  iconAlignment="end"
>
  Create user
</Button>

<Button
  size="large"
  iconName="PhoneIcon"
  iconVariant="solid"
  iconAlignment="start"
>
  Create user
</Button>
<Button
  size="large"
  iconName="PhoneIcon"
  iconVariant="solid"
  aria-label="Create user"
/>
<Button
  size="large"
  iconName="PhoneIcon"
  iconVariant="solid"
  iconAlignment="end"
>
  Create user
</Button>

<Button
  size="large"
  iconName="PhoneIcon"
  iconVariant="solid"
  iconAlignment="start"
>
  Create user
</Button>
<Button
  size="large"
  iconName="PhoneIcon"
  iconVariant="solid"
  aria-label="Create user"
/>
<Button
  size="large"
  iconName="PhoneIcon"
  iconVariant="solid"
  iconAlignment="end"
>
  Create user
</Button>

Accessibility

If the button does not include a textual label, such as a button that only contains an icon, an aria-label or aria-labelledby prop need to be provided to support assistive technology such as screen readers.

In order to support internationalization, provide a localized string to the children or aria-label prop.