import { ExampleCodeBlock, SymbolDoc } from '@workday/canvas-kit-docs';
import Basic from './examples/Basic';
import BasicWithHeading from './examples/BasicWithHeading';
import FixedColumn from './examples/FixedColumn';
import RightToLeft from './examples/RightToLeft';
import BaseHtmlTable from './examples/BaseHtmlTable'

# Canvas Kit Table

`Table` is a simple styled compound component that renders a
[table](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table) element. It is used to
present information in a two-dimensional table comprised of rows and columns of cells containing
data. `Table` is built off of `BaseTable` and is using [CSS Grid](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout) features.

## Installation

```sh
yarn add @workday/canvas-kit-react
```

## Usage

### Basic Example

Users may not want to use a `caption` so they can import [Heading](/components/text/heading/) or
[Text](/components/text/text/) instead. This will give the user more flexibility around the
customization of the title/heading of their table.

<ExampleCodeBlock code={BasicWithHeading} />

### Right to Left

Table supports right-to-left languages when specified in the CanvasProvider theme.

<ExampleCodeBlock code={RightToLeft} />

### Example with Caption

Users are free to use a `caption` instead of a heading. A `caption` is not required but it is good
for
[accessibility](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table#accessibility_concerns)
purposes.

<ExampleCodeBlock code={Basic} />

### Fixed Column

Users may add styles to the `Table.Header` to render a fixed column. The example below assigns a
`width` to the `Table` to guarantee the fixed column is triggered, but you are free to omit the
`width` if you would only like the fixed column to be triggered if necessary.

<ExampleCodeBlock code={FixedColumn} />

### Base Html Table Example

If a user needs a standard HTML [table](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table) with no [CSS Grid](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout) features, then they can use the `BaseTable` component. 

<ExampleCodeBlock code={BaseHtmlTable} />

### Which Component Should I Use?

> If a user wants [CSS Grid](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout) features with their Table, then use the [Table](/components/containers/table/) component.

> If a user __does not__ want [CSS Grid](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout) features with their Table, then use the [BaseTable](/components/text/heading/) component. 

### Advanced

You can also find several advanced Table examples in our Storybook Examples section.

- [Expandable Rows](/docs/examples-tables-advanced--expandable-rows)
- [Selectable Rows ](/docs/examples-tables-advanced--selectable-rows)
- [Sortable Column Headers](/docs/examples-tables-advanced--sortable-column-headers)

### Custom Styles

Table and its subcomponents support custom styling via the `cs` prop. For more information, check
our
["How To Customize Styles"](https://workday.github.io/canvas-kit/?path=/docs/styling-how-to-customize-styles--docs).

## Component API

<SymbolDoc name="Table" fileName="/react/" />