docs: improve documentation in Credentials provider (#12873)

Co-authored-by: Thang Vu <hi@thvu.dev>

Author: halvaradop

docs/pages/getting-started/authentication/credentials.mdx

@@ -35,7 +35,53 @@ so there are no plans to remove this provider.
 
 ### Credentials Provider
 
-First, let's initialize the `Credentials` provider in the Auth.js configuration file. You'll have to import the provider and add it to your `providers` array.
+To use the `Credentials Provider`, you’ll first need to import and configure it in your `Auth.js` setup. This provider allows you to implement custom login logic based on form input values.
+
+Here’s how to set it up:
+
+1. Import the provider.
+2. Add it to the `providers` array in your `Auth.js` config.
+3. Define the `credentials` and `authorize` fields.
+
+#### `credentials`
+
+The `credentials` object defines the input fields displayed on the default sign-in page. These inputs are automatically rendered on the route:
+
+- `/api/auth/signin` (Next.js)
+- `/auth/signin` (Other frameworks)
+
+Each field accepts the following properties:
+
+- `label`: Input label
+- `type`: HTML input type (`text`, `password`, etc.)
+- `placeholder`: Placeholder text
+
+> These fields are also passed to the `authorize` function under the `credentials` argument.
+
+For more details, see the [Built-in Pages guide](https://authjs.dev/guides/pages/built-in-pages).
+
+```ts
+Credentials({
+  credentials: {
+    email: {
+      type: "email",
+      label: "Email",
+      placeholder: "johndoe@gmail.com",
+    },
+    password: {
+      type: "password",
+      label: "Password",
+      placeholder: "*****",
+    },
+  },
+})
+```
+
+#### `authorize`
+
+The `authorize` function handles the custom login logic and determines whether the credentials provided are valid.
+
+It receives the input values defined in `credentials`, and you must return either a user object or `null`. If `null` is returned, the login fails.
 
 <Code>
 <Code.Next>
@@ -541,3 +587,14 @@ export const { handle } = SvelteKitAuth({
 
 </Code.Svelte>
 </Code>
+
+<Callout>
+
+When authorize returns null, Auth.js handles the error in one of two ways:
+
+Using built-in pages:
+
+- The user is redirected to the login page with the query string: `?error=CredentialsSignin&code=credentials`. You can customize the code using the [credentials provider options](https://authjs.dev/reference/core/providers/credentials#returns).
+- Using form actions or custom error handling (e.g., in Remix, SvelteKit): The error is thrown as credentialssignin and must be caught manually in your server action. See more in the [Auth.js error reference](https://authjs.dev/reference/core/errors#credentialssignin).
+
+</Callout>